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DESIGN AND IMPLEMENTATION OF A BACKGROUND OF THE INVENTION 

CLIENT/SERVER FRAMEWORK FOR 1. Field of the Invention 

FEDERATED MULTI-SEARCH AND UPDATE . .. ... . . 

ACROSS HETEROGENEOUS DATASTORES ^ ™> e f° a m S eneraI to df*** management 

5 systems performed by computers, and in particular, to a 

CROSS-REFERENCE TO RELATED design and implementation of a client/server framework for 

APPLICATIONS federated multi-search and update across heterogeneous 

datastores. 

This application is related to the following co-pending 2. Description of Related Art 

and commonly-assigned patent applications: 10 ^ presem mvention relates t0 a system and melhod for 

Application Ser. No. 09/400,532, entitled "MANAGING representing and searching multiple heterogeneous datas- 

RESULTS OF FEDERATED SEARCHES ACROSS tores and managing the results of such searches. Datastore is 

HETEROGENEOUS DATASTORES WITH A FED- a term used to refer to a generic data storage facility, such as 

ERATED RESULT SET CURSOR OBJECT/' filed on a relational data base, flat-file, hierarchical data base, etc. 

same date herewith, by Basuki N. Soertarman et al.; 15 Heterogeneous is a term used to indicate that the datastores 

Application Sen No. 09/399,690, entitled "THE ARCHI- need not be similar to each other. For example, each datas- 

TECTURE AND IMPLEMENTATION OF A tore may store different types of data, such as image or text, 

DYNAMIC RMI SERVER CONFIGURATION HIER- or each datastore may be based on a different theory of data 

ARCHYTO SUPPORT FEDERATED SEARCH AND model, such as Digital Library/Visuallnfo or Domino 

UPDATE ACROSS HETEROGENEOUS 20 Extended Search (DES). 

DATASTORES," filed on same date herewith, by For nearly half a century computers have been used by 
Kehsing J. Chou et al.; businesses to manage information such as numbers and text, 
Application Ser. No. 09/399,682, entitled "ARCHITEC- mainly in the form of coded data. However, business data 
TURE TO ENABLE SEARCH GATEWAYS AS PART represents only a small part of the world's information. As 
OF FEDERATED SEARCH," filed on same date 25 storage, communication and information processing tech- 
herewith, by Kehsing J. Chou et al.; nologies advance, and as their costs come down, it becomes 
Application Ser. No. 09/399,699, entitled "DELAYED more feasible to digitize other various types of data, store 
DELIVERY OF QUERY RESULTS OR OTHER large volumes of it, and be able to distribute it on demand to 
DATA FROM A FEDERATED SERVER TO A FED- 3Q at meir P lace of business or home. 
ERATED CLIENT UNTIL SUCH INFORMATION IS New digitization technologies have emerged in the last 
NEEDED/' filed on same date herewith, by M. W. decade to digitize images, audio, and video, giving birth to 
Huang et al.; a new type of digital multimedia information. These multi- 
Application Ser. No. 09/399,695, entitled "IMPROVED media objects are quite different from the business data that 
EXTENDED DATA OBJECT ARCHITECTURE FOR 35 computers managed in the past, and often require more 
. HANDLING MULTI-STREAMING AND COMPLEX advanced information management system infrastructures 
MULTI-DIMENSIONAL FILES," filed on same date witn new capabilities. Such systems are often called "digital 
herewith, by Kehsing J. Chou et al.; libraries." 
Application Ser. No. 08/852,062, now U.S. Pat. No. Bringing new digital technologies can do much more than 
5,960,438 entitled "CLASS HIERARCHY FOR 40 just replace physical objects with their electronic represen- 
OBJECT AGGREGATION REPRESENTATION OF tation - 11 cables instant access to information; supports fast, 
RELATIONAL DATABASE ROWS WITH CELLS accurate, and powerful search mechanisms; provides, new 
HAVING NONTRADIHONAL DATATYPES/' filed "experiential" (i.e. virtual reality) user interfaces; and imple- 
on May 6, 1997, by Daniel T. Chang et al.; ments new wa y s of protecting the rights of information 
Application Ser. No. 08/852,055, now U.S. Pat. No. 45 ° w <*rs - These properties make , digital library solutions even 
5,924,100 entided "FLEXIBLE OBJECT REPRESEN- ^ore attractive and acceptable not only to corporate IS 
TATION OF RELATIONAL DATABASE CELLS organizations but to the mformaUon owners, publishers and 
HAVING NONTRADIHONAL DATATYPES," filed SerVlce P r0Vlders ; 

on May 6, 1997, by Daniel T. Chang et al.; Generally, business data is created by a business process 

Application Ser. No. 09/052,678, now U.S. Pat. No. 50 ( *° ^ tickct r f crvatioa > a dc P osit at *° bank > a * d * 

6,272,488 entitled «MANa6in6 RESULTS OF FED- ^ P™ cssin g at m ~™ ™ examples). 

ERATED SEARCHES ACROSS HETEROGENEOUS M f ° f J* 80 P / OCeSSCS h , aV ? bccQ ™ated by computers 

DATASTORES WITH A FEDERATED OOLLEC ^ J™*™ "f, f J°T { ^\tf 

-rrrwr nDTcrr» «i a a 1 1 nno u • i ^ numbers). Therefore it is usually structured coded data. 

TION OBJECT, filed on Apr. 1, 1998, by Daniel T. XA u . j. 4 , 4 , , „ 

Chane et al ■ 55 Mlllti media data > 00 me contrary, cannot be fully pre- 

* '' structured (its use is not fully predictable) because it is the 

Application Ser. No. 09/052,680, now U.S. Pat. No. result of the creation of a human being or the digitization of 

6,263,342 entitled "FEDERATED SEARCHING OF m object of me real world (x _ ravs? geophysical mapping, 

HETEROGENEOUS DATASTORES USING A FED- etc<) r ; tner ^ a com uter ^thm. 

ERATED DATASTORE OBJECT" filed on Apr. 1, _ rL . * . . A , . A . . t . P 

100ft k n •i TPk * 1 60 ^h e avera 8 e size °f business data in digital form is 

lyys, by Daniel 1. Lnang et al.; relatively small. A banking record— including a customers 

Application Ser. No. 09/052,679, now U.S. Pat. No, name, address, phone number, account number, balance, 

6,233,586 entitled "FEDERATED SEARCHING OF etc.— represents at most a few hundred characters, i.e. few 

HETEROGENEOUS DATASTORES USING A FED- hundreds/thousands of bits. The digitization of multimedia 

ERATED QUERY OBJECT," filed on Apr. 1, 1998, by 65 information (image, audio, video) produces a large set of bits 

Daniel T. Chang et al.; called ^ « 0D ject" or "blobs" (Binary Urge Objects). For 

each of which is incorporated by reference herein. example, a digitized image of the parchments from the 
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Vatican library takes as much as the equivalent of 30 (i.e. , "methods"). A "class" defines the implementation of a 

million characters (30 MB) to be stored. The digitization of particular kind of object, the variables and methods it uses, 

a movie, even after compression, may take as much as the and the parent class it belongs to. 

equivalent of several billions of characters (3-4 GB) to be Some known programming tools that can be used for 

stored. 5 developing search and result-management frameworks 

Multimedia information is typically stored as much larger include IBM VisualAge C++, Microsoft Visual C++, 

objects, ever increasing in quantity and therefore requiring Microsoft Visual J++, and Java. 

special storage mechanisms. Classical business computer There j s a nee( j m me art f or an improved federated 

systems have not been designed to directly store such large system. In particular, there is a need in the art for an 

objects. Specialized storage technologies may be required io i mprove d client/server framework for federated multi- 

for certain types of information, e.g. media streamers for searcn ^ update across heterogeneous datastores. 
video or music. Because certain multimedia information 

needs to be preserved "forever" it also requires special SUMMARY OF THE INVENTION 

storage management functions providing automated back-up . . 

and migration to new storage technologies as they become 15 ( To overcome the limitations in the prior art described 

available and as old technologies become obsolete. above > and to o^rcome other limitations that will become 

Finally, for performance reasons, the multimedia data is apparent upon reading and understanding the present 

i j • *l ■ ■* c *u ■ j i t v t specification, the present invention discloses a method, 

often placed m the proximity of the users with the system r ^ j . ■ i r r j * 1 

, j. . : , . . . rr- • fi apparatus, and article of manufacture for a design and 

supporting multiple distributed object servers. This often ■ i * *• * i- *# * i * r j * j 

i f u * 1*** * j • on implementation of a client/server framework for federated 

requires a logical separation between applications, indices, ^ LJJi ... j , . 

j Jt , -j j «. u • iL multi-search and update across heterogeneous datastores. 

and data to ensure independence from any changes in the r & 

location of the data According to an embodiment of the invention, a technique 

The indexing of business data is often imbedded into the for manipulating data in one or more heterogeneous datas- 

data itself. When the automated business process stores a tores at a computer is provided. An object-onented model is 

person's Dame in the column "NAME," it actually indexes 25 Provided for integrating one or more heterogeneous datas- 

that information. Multimedia information objects usually do *? m ^ a ***** datastore. One or more heterogeneous 

not contain indexing information. This "meta data" needs to datastores and a federated datastore are generated based on 

be created in addition by developers or librarians. The me object-oriented model. Hie generated datastores are 

indexing information for multimedia information is often q «*> * Crated composition, 

kept in "business like" databases separated from the physical 30 BRIEF DESCRIPTION OF THE DRAWINGS 
object. 

In a Digital Library (DL), the multimedia object can be Referring now to the drawings in which like reference 

linked with the associated indexing information, since both numbers represent corresponding parts throughout: 

are available in digital form. Integration of this legacy 35 FIG. 1 is a diagram illustrating a computer architecture 

catalog information with the digitized object is crucial and that could be used in accordance with the present invention; 

is one of the great advantages of DL technology. Different FIG. 2 is a diagram illustrating a class hierarchy for Data 

types of objects can be categorized differently as appropriate Object classes; 

for each object type. Existing standards like MARC records mr* i • j- _ -n * *• i w u * 

c i-. . ^. * ^ ... * . ^ FIG. 3 is a diagram illustrating a class hierarchy for 

for libraries, Finding Aids for archiving of special ^ Datastore dasses; 

collections, etc. . . can be used when appropriate. . . . . - 

, r A . . . FIG. 4 is a diagram illustrating one composition of a 

Tne indexing information used for catalog searches in federated datastore- 

physical libraries is mostly what one can read on the covers ' 

of the books: authors name, title, publisher, ISBN, . . . FIG - 5 fe a of an extended Grand Portal archi- 

enriched by other information created by librarians based on 45 tecture i 

the content of the books (abstracts, subjects, keywords, . . . ). FIG. 6 is a diagram illustrating individual datastores and 

In digital libraries, the entire content of books, images, federated compositions; and 

music, films, etc . . . are available and "new content" FIG. 7 is a flow diagram illustrating one use of the 

technologies are needed; technologies for full text searching, client/server framework for federated multi-search and 

image content searching (searching based on color, texture, 50 update across heterogeneous datastores. 
shape, etc . . . ), video content searching, and audio content 

searching. The integrated combination of catalog searches DETAILED DESCRIPTION OF THE 

(e.g. SQL) with content searches will provide more powerful PREFERRED EMBODIMENT 

search and access functions. These technologies can also be }n ^ following description of the preferred embodiment, 

used to partially automate further indexing, classification, S5 re f ere nce is made to the accompanying drawings which 

and abstracting of objects based on content. fonn a part nereof? and in which ^ snown by way of 

To harness the massive amounts of information spread illustration a specific embodiment in which the invention 

throughout these networks, it has become necessary for a may be practiced. It is to be understood that other embodi- 

user to search numerous storage facilities at the same time ments may be utilized and structural and functional changes 

without having to consider the particular implementation of eo may be made without departing from the scope of the 

each storage facility. present invention. 

Object-oriented approaches are generally better suited for Federated Architecture 

such complex data management. The term "object-oriented" FIG. 1 is a diagram illustrating a computer architecture 

refers to a software desigD method which uses "classes" and that could be used in accordance with the present invention, 

"objects" to model abstract or real objects. An "object" is the 65 The present invention is described herein by way of example 

main building block of object-oriented programming, and is and is not intended to be limited to the described embodi- 

a programming unit which has both data and functionality ment. The description of the preferred embodiment is based 
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on, but certainly not limited to, the IBM design of Java 
Grand Portal Class Library, the Digital Library Java Appli- 
cation Programming Interface (API). 

The Java Grand Portal 120 is comprised of client and 
server classes. In particular, Java Grand Portal is a set of 
Java classes which provides access and manipulation of 
local or remote data stored in Digital Library storage facili- 
ties. It uses Java APIs based on OMG-Object Query Services 
(OQS) and a Dynamic Data Object protocol, which is a part 
of OMG/Persistence Object Services. 

The Java APIs provide multi-search capabilities such as: 

1. Searching within a given datastore using one or a 
combination of supported query types, i.e. 

Parametric query — Queries requiring an exact match on 
the condition specified in the query predicate and the 
data values stored in the datastore. 

Text query — Queries on the content of text fields for 
approximate match with the given text search 
expression, e.g. the existence (or non-existence) of 
certain phrases or word-stems. 

Image query — Queries on the content of image fields for 
approximate match with the given image search 
expression, e.g. image with certain degree of similarity 
based on color percentages, layout, or texture. 

2. Each search type is supported by one or more search- 
engines. 

3. Searching on the results of a previous search. 

4. Searching involving heterogeneous datastores. . 

The Digital Library Grand Portal classes provide a con- 
venient API for Java application users; the applications can 
be located at local or remote sites. Java classes will typically 
reside on both server and client sides; both sides providing 
the same interface. The client side of Java classes commu- 
nicates with the server side to access data in the Digital 
Library through the network. Communication between cli- 
ent and server sides is done by these classes; it is not 
necessary to add any additional programs. 

In particular, FIG. 1 is an architectural diagram outlining 
the structure of the federated search for Digital Library 
repositories using the federated datastore 100, comprised of 
a federated datastore client and server. A federated datastore 
100 is a virtual datastore which combines several heteroge- 
neous datastores 102 into a consistent and unified conceptual 
view. This view, or a federated schema, is established via 
schema mapping 104 of the underlying datastores. The users 
interact with a federated datastore 100 using the federated 
schema, without needing to know about the individual 
datastores 102 which participate in the federated datastore 
100. 

One embodiment of the invention provides a federated 
result set cursor object across heterogeneous datastores. In 
one embodiment of the invention, one or more classes 
implement the federated result set cursor object, and one or 
more methods are provided to manipulate the federated 
result set cursor object. In one embodiment, the class 
definitions and methods reside at the federated datastore 
client and server. 

The federated datastore 100 does not have a correspond- 
ing back-end client. Since it is a virtual datastore, the 
federated datastore 100 relies on the underlying physical 
back-end client associated with it, such as the DL client (i.e., 
Digital Library client), OnDemand, Visuallnfo, DB2, etc. 
Digital Library, OnDemand, Visuallnfo, and DB2 are all 
products from International Business Machines Corpora- 
tion. As mentioned before, this association is established by 
a schema mapping component 104. 
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The communication between the federated datastore 100 
client and server can be done by any appropriate protocol. 
On top of Java Grand Portal client classes, the users can 
develop application programs using, for example, any exist- 
ing Java Beans 122 development environment. 

Hie federated datastore 100 coordinates query evaluation, 
data-access, and transaction processing of the participating 
heterogeneous datastores 102. Given the federated schema, 
a multi-search query can be formulated, executed, and 
coordinated to produce results in the form of a datastore- 
neutral dynamic data object. 

Note that each heterogeneous datastore and the federated 
datastore are created using one datastore definition or super- 
class. The federated datastore 100 and the heterogeneous 
datastores 102 are all subclasses of a class called Datastore, 
therefore, all of these datastores 100 and 102 have the same 
interface. Therefore, a user would be able to access the 
federated datastore 100 and the heterogeneous datastores 
102 in a consistent and uniform manner. 

Additionally, the objects stored in the federated datastore 
100 and the heterogeneous datastores 102 are subclasses of 
a Data Object class. The Data Object class includes sub- 
classes for dynamic data objects (DDOs) and extended data 
objects (XDOs). ADDO has attributes, with type, value, and 
properties. The value of an attribute can be a reference to 
another DDO or XDO, or a collection of DDOs or XDOs. 

FIG. 2 is a diagram illustrating a class hierarchy for Data 
Object classes. The objects stored in and manipulated by the 
datastores and fetch operations belong to data object classes. 
These objects are returned as the result of a fetch, or created 
and used in CRUD (add, retrieve, update, delete) operations. 

ADataObjectBase 200 is an abstract base class for all data 
objects known by datastores. It has a protocol attribute, that 
indicates to the datastore which interface can be used to 
operate on this object. A XDOBase 210 is the base class used 
to represent user-defined-types (UDT) or large objects. In 
particular, the XDOBase 210 is the base class for some 
user-defined types 212 and XDOs 214. AXDO 214 repre- 
sents complexUDTs or large objects (LOB). This object can 
40 exist stand-alone or as a part of a DDO 236. Therefore, it has 
a persistent object identifier and CRUD operations capabili- 
ties. 

Blob 216 is a base class for BLOBs as a place holder to 
share all generic operations pertaining to BLOBs, Clob 218 
is a base class for CLOBs (Character Large Objects) as a 
placeholder to share all generic operations pertaining to 
CLOBs. DBClob 220 is a base class for DBCLOBs 
(database character large object) as a placeholder to share all 
generic operations pertaining to DBCLOBs. BlobDB2 222 
represents a BLOB specific to DB2, and BlobDL 22 repre- 
sents a BLOB specific to DL. Similarly, though not shown, 
there may be subclasses for ClobDB2, ClobDL, etc. 

A DataObject 230 is a base class for PersistentObject 232 
and DDOBase 234. A PersistentObject 232 represents a 
specific object whose code is statically generated and com- 
piled. This type of object will not be covered in this 
document. A DDOBase 234 is a base class for a dynamic 
data object 236 (without the CRUD methods). A DDO 
(Dynamic Data Object) 236 represents generic data objects 
which are constructed dynamically at runtime. This object 
fits well with query and browsing activities in Grand Portal 
where objects are only known and generated at runtime. It 
supports the CRUD operations (add, retrieve, update, and 
delete), and, with the help of its associated datastore, a DDO 
can put itself into and out of the datastore. 

One skilled in the art would recognize that these are only 
example classes and subclasses and other structures maybe 
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used for objects and other classes or subclasses may be a single or multiple heterogeneous da tastores participating in 

added to or removed from the tree shown in FIG. 2. a federation. The datastores can be of the same or different 

With respect to the notion of "federation", each partici- types, and in a mixture of local or client/server configura- 

pating datastore preserves the right to maintain its tions. Several different search-engines, such as, text search 

"personality", i.e. its own query language, data-model or 5 and image search engines, may be added to enrich the 

schema, method of interaction, etc, and at the same time combined multi-search capability of the system, 

cooperating in a federation to provide a federated schema. Tq articul ^ embo diment of the invention provides an 

This design allows the users to preserve the natural view to • _ . j <? c i- ♦# i- 

,1 ■ r *t j * *. 11 *u *- environment and facilities for client/server application 

their f avonte datastore as well as access them in conjunction , , ... . * , , ■« . v. 1 

with other datastores in a federated context. in development with object-oriented class libraries. Example 

The federated datastore 100 can combine the participating 10 object-onented class libraries are described in more detail 

native datastores in two ways: below * ^ object-oriented class hbranes support a consis- 

With mapping. As described above, mapping of concepts tent &*»w0rk for representing a variety of data-storage 

across participating datastores is established to provide facilities via the use of datstore objects, including the 

a unified conceptual view Based on this federated federation of several heterogeneous datastores. Additional 

schema, federated queries with both join and union 15 datastore types can be defined and incorporated in the 

expressions can be formulated. federation. 

Without mapping. In this case, the federated datastore 100 The object-oriented class libraries support a consistent 

only reflects the union of each participating datastore's framework for data-access across a single or heterogeneous 

conceptual view. Although it coordinates query pro- datastore via the implementation of dynamic data objects 

cessing and data-access for each underlying datastore, 20 and extender data objects, 

the federated datastore 100 must accept queries in each 7^ object-oriented class libraries support a consistent 

datastore's native language since the query translation framework for performing multi-search using a variety of 

process can not be performed without mapping. In searcn engines and for performing federated search via the 

addition, since there is no conceptual mapping between federated datastores. 

datastores, the FederatedQuery 19 results can only 25 ^ object . oriented class Ubraries support a consistent 

reflect the union of results from each datastore. framework for handling a variety of multi-media data via the 

Tne embodiment of the invention is incorporated into one ^mentation of an extender data object and its exten- 

or more software programs that reside at the federated s ^ Qns 

datastore 100. Generally the software programs .and the ^ object ^ riented ckss nbt ^ es rt , amliamt 

mstructions derived therefrom, are all tangibly embodied m 30 for client/server ^mentation of the above, 

a computer-readable medium, e.g. one or more of the data ^ ,-. • ^ ■ , . 

storage devices, which may be connected to the federated . ™ e object-oriented class hbranes support a consistent 

datastore 100. Moreover, the software programs and the &^ w °* [defining a dynamic client/server configura- 

instructions derived therefrom, are all comprised of instruc- on an oa ancing. 

tions which, when read and executed by the computer 35 Modern day application programs work in a complex 

system 100, causes the computer system 100 to perform the environment. The present invention provides support for a 

steps necessary to implement and/or use the present inven- Dumber °{ fcatur f- Non-traditional data types, such as text, 

tion. Under control of an operating system, the software ™«S?. V0ice > •?<* video are supported, along with capabih- 

programs and the instructions derived therefrom, may be Ucs for capturing, storing/archiving, searching, updating, 

loaded from the data storage devices into a memory of the 40 and presenting these data types. The ability to perform a 

federated datatstore 100 for use during actual operations. multi-search (i.e., a combination of parametric, text, and 

Tnus, the present invention may be implemented as a W1 t th 1 . thc hel P of P ro f r en ^ nes 18 
method, apparatus, or article of manufacture using standard supported The ability to access and update data from a 
programrning and/or engineering techniques to produce 01 ; heterogeneous data source in a federated or non- 
software, firmware, hardware, or any combination thereof. 45 federated environment is supported. The ability to work in a 
The term "article of manufacture" (or alternatively, "com- cfient/server environment with dynamic topology where 
puter program product") as used herein is intended to new servers can be added or removed from the configuration 
encompass a computer program accessible from any 15 supported. The ability to support a choice of different 
computer-readable device, carrier, or media. Of course, implementation languages, such as Java, C++, and Visual 
those skilled in the art will recognize many modifications 50 Basic, in diverse customer shops and machine platforms is 
may be made to this configuration without departing from supported. U» ability to support applications launched from 
the scope of the present invention. me World Wlde Web IS av ^able. Tte ability to support 

Those skilled in the art will recognize that the exemplary ^-usable component based software development is avail- 
environment illustrated in FIG. 1 is not intended to limit the a ^ e * 

present invention. Indeed, those skilled in the art will 55 FIG. 3 is a diagram illustrating a class hierarchy for 

recognize that other alternative hardware environments may Datastore classes. A main datastore class 300 is an abstract 

be used without departing from the scope of the present basc class 0- e *> superclass) for all datastores. In particular, 

invention. some datastore classes that are based on the datastore class 

300 and inherit its characteristics are the following: a DL 

A Design and Implementation of a Client/server 6Q Datastore class 30 2, a Visuallnfo Datastore class 304, a 

Framework for Federated Multi-search and Update Federated Datastore class 306, and an OnDemand Datastore 

Across Heterogeneous Datastores class 30g It k tQ be understood thal ^ techniques of the 

An embodiment of the invention provides a design and invention may be applied to any data source and is not 

implementation of a client/server framework for federated limited to the mentioned datastores. 

multi-search and update across heterogeneous datastores. 65 FIG. 4 is a diagram illustrating one composition of a 

A consistent framework is provided for developing client/ federated datastore. The federated datastore 400 connects to 

server application programs for multi-search and update on heterogeneous datastores 402,404,406, and 408. As 
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illustrated, a federated datastore 406 may connect to and be 
nested under federated datastore 400. Additionally, the fed- 
erated datastore 406 may connect to heterogeneous datas- 
tores 410,412, and 414. The depicted architecture is only a 
sample, and one skilled in the art would recognize that other 5 
examples fall within the scope of the invention. 

FIG. 5 is a diagram of an extended Grand Portal archi- 
tecture. A Grand Portal client for a federated client datastore 
500 is connected to a Grand Portal server for a federated 
server datastore 502. Another federated client/server system 10 
504 may be connected to the federated server 502. A Grand 
Portal client/server system for an OnDemand (OD) datastore 
506 may be part of the federation. Additionally, a Grand 
Portal client/server system for a Digital LibraryNisualinfo 
(DL/VI) datastore 508 may be part of the federation. As with 15 
any of the datastores discussed herein, a user may access the 
client or the server directly. Therefore, user applications may 
reside either at the client or the server. 

FIG. 6 is a diagram illustrating individual datastores and 
federated compositions. In particular, a datastore can be 20 
configured as a stand-alone or as part of a federation. 
Additionally, a federated datastore can be composed of any 
number of datastores, including other federated datastores. 
Stand-alone datastores may be accessed directly by auser. 
The following are example stand-alone datastores in FIG. 6: 25 
a Digital Libt (DL) datastore 600, an OnDemand datastore 
602, a Visualnfo/400 datastore 604, a Domino. Doc datastore 
606, or a ImagePlus/390 datastore 608. Additionally, there 
may be multiple federated compositions 610 and 612. A 
federated composition 612 may include individual datas- 30 
tores 614, 616, and 620, along with another federated 
datastore 618. 

Part of the novelty and uniqueness of the Grand Portal 
architecture is that it is rich and robust enough to allow a 3S 
user to compose a search in the following configurations: 

1. Search against a single datastore either from a client or 
a server configuration. Depending on the target datas- 
tore features, the architecture may support multi-search 
involving several different search engines (text and 40 
image search) or an update function. 

2. Non-federated search against several datastores. Non- 
federated means that there is no mapping used. The 
user manages the search to each native datastore and 
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processes the results according to a specific application 
to solve a specific problem. In this case, the datastore 
could be a gateway. 

3. Federated search across several datastores, including 
other federated datastores 

4. A mixture of 2 and 3. 

5. Search in a combination of different platforms (e.g., 
AMx, NT/Win98) using a variety of languages (e.g., 
Java, C++, Visual Basic) 

FIG. 7 is a flow diagram illustrating one use of the 
client/server framework for federated multi-search and 
update across heterogeneous datastores. Initially, in block 
700 a federated composition is built by generated datastores 
from datastore classes. For example, a federated datastore is 
generated from a federated datastore class that is based on a 
base datastore class. Similarly, a Digital Library datastore, a 
QBIC datastore, and a Text datastore may be generated from 
their corresponding datastore classes, each of which is based 
on the base datastore class. 

Then, in block 702, data is stored in the datastores using 
objects based on object classes. For example, the objects 
may be dynamic data objects or extended data objects. On 
type of extended data object is a binary large object. Next, 
searching may be performed across the heterogeneous 
(native) datastores, block 704. This is done using query 
objects. For example, the query can be a combined query 
object (for retrieving a combination of data, such as text, 
image or parametric), or the query can be a text query, an 
image query, a parametric query, or a SQL query. 

In order for the federated datastore to communicate with 
the native datastores, shema mapping objects are used, block 
706. Once the mapping is performed and the query is 
submitted to each native datastore, in block 708, data is 
returned from each native datastore in the form, for example, 
of a collection object or a result set cursor object. Then, in 
block 710, auser or application program may iterate thorugh 
the returned data using an iterator object. 

Class Libraries 
1. Datastore Base Class 

The dkDatastore is the class on which each other datastore 
class is based. An example class definition for dkDatas- 
tore is set forth below. 



dkDatastore 

Interface com.ibm. mm. sdic.conxmon. dkDatastore 
public interface dkDatastore 
extends dkQueryManager 

{ 

public abstract void connect(String datastare__name, 
String user_name, 
String authentication, 

String connect_string) throws DKException, Exception 
public abstract void disconnect ) throws DKException, Exception 
public abstract Object getOption(int option) throws DKException, Exception 
public abstract void setOption(int option, 

Object value) throws DKException, Exception 
public abstract Object evaluate(String command, 

short commandLangType, 

DKNVPair params[ ]) throws DKException, Exception 
public abstract Object evaluate(dkQuery query) throws DKException, Exception 
public abstract Object evaluate(DKCQExpr qe) throws DKException, Exception 
public abstract dkResultSetCursor execute(String command, 
short commandLangType, 

DKNVPair params[ J) throws DKException, Exception 
public abstract dkResultSetCursor execute(dkQuery query) throws DKException, Exception 
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public abstract dkResultSetCursor execute(DKCQExpr qc) throws DKException, Exception 
public abstract void executeWithCallback{dkQuery qo, 

dkCallback callbackObj) throws DKException, Exception 
public abstract void txecuteWithCallback(String command, 

short commandLangiype, 

DKNVPair paramsf ], 

dkCallback callbackObj) throws DKException, Exception 
public abstract void executeWithCallback(DKCQExpr qe, 

dkCallback callbackObj) throws DKException, Exception 
public abstract dkQuery createQuery (String command, 

short commandLangType, 

DKNVPair params[ ]) throws DKException, Exception 
public abstract dkQuery createQuery (DKCQExpr qe) throws DKException, Exception 
public abstract void addObject(dkDataObject ddo) throws DKException, Exception 
public abstract void deleteObject(dkDataObject ddo) throws DKException, Exception 
public abstract void retrieveObjcct(dkDataObject ddo) throws DKException, Exception 
public abstract void updateObject(dkDataObject ddo) throws DKException, Exception 
public abstract void commit( ) throws DKException, Exception 
public abstract void iollback( ) throws DKException, Exception 
public abstract boolean isConnectedf ) throws Exception 
public abstract String datastoreName( ) throws Exception 
public abstract String datastoreType( ) throws Exception 
public abstract DKHandle connection( ) throws Exception 
public abstract DKHandle handle(String type) throws Exception 
public abstract String userName( ) throws Exception 

public abstract dkCollection listDataSources( ) throws DKException, Exception 
public abstract String[ ] listDataSourceNames( ) throws DKException, Exception 
public abstract Object listServers( ) throws DKException, Exception 
public abstract Object lis (Schema { ) throws DKException, Exception 

public abstract Object lktSchemaAtiributes(String schemaEntry) throws DKException, public 

abstract dkCollection listEntities( ) throws DKException, Exception 

public abstract dkCollection listScarchableEntitiesf ) throws DKException, Exception 

public abstract String[ ] listEntity Names ( ) throws DKException, Exception 

public abstract Stringf ] listSeaTchableEntityNamesf ) throws DKException, Exception 

public abstract dkCollection IistEntityAttxs(String entityName) throws DKException, 

Exception 

public abstract String[ ] listEntity AttrNames(String entityName) throws DKException, 
Exception 

public abstract dkDatastojeDef datastoreDef( ) throws DKException, Exception 
public abstract String registerMappingfDKNVPair sourceMap) throws DKException, 
Exception 

public abstract void unRegisterMapping(String mappingName) throws DKException, 
Exception 

public abstract String! ] 1 istMapp in gNam es ( ) throws DKException, Exception 
public abstract dkSchemaMapping getMapping (String mappingName) throws DKException, 
public abstract dkExtension getBxtension(String extensionName) throws DKException, public 
abstract void addExtension(String extensionName, 

dkExtension extensionObj) throws DKException, Exception 
public abstract void removeBxtensian (String extensionName) throws DKException, Exception 
public abstract String[ ] listExtensionNamcs( ) throws DKException, Exception 
public abstract DKDDO createDDO(String objectType, 

int Flags) throws DKException, Exception 
public abstract void changePassword(String userld, 

String oldPwd, 

String newPwd) throws DKException, Exception 
public abstract void destroy( ) throws DKException, Exception 
} 



The following methods are part of the dkDatastore class: 
public abstract void connect(String datastore_name, 
String user_jiame, 

String authentication, S5 
String connect string) throws DKException, Exception 
Connects to a datastore. 
Parameters: 

datastore_name — the datastore name used for connection 60 
user_name — the user name used for connection 
authentication — the authentication used for connection 
connect_string — the connect string used for connection. 
This is used to provide additional connection options. 65 

public abstract void disconnect( ) throws DKException, 

Exception 



Disconnects to a datastore. 
public abstract ObjectgetOption(int option) throws 
DKException, Exception 

Gets a datastore option. 

Parameters: 

option — the option identifier 
Returns: 
an option value 
public abstract void setOption(int option, 

Object value) throws DKException, Exception 

Sets a datastore option. 

Parameters: 

option — the option identifier 
value — the option value 
public abstract Object evaluate(String command, 
short commandLangType, 
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D NVPair params[ ]) throws DKException, Exception Parameters: 

Evaluates a query. command — a query string 

Parameters: commandLang— a query type 

command— a query string 5 params— additional query option in name/value pair 

commandLang— a query type callbackObj— a dkCallback object 

..... , • / 1 public abstract void execute WithCallback(DKCQExpr qe, 

params — additional query option in name/value pair r ^ ^ 

dkcallback callbackObj) throws DKException, Exception 
Returns: . 

„ _ , , Executes the query with callback function, 

a collection of the results ^ Parameters* 

public abstract Object evaluate(dkQuery query) throws 

DKException, Exception a c ™mon query expression object 

Evaluates a auerv callbackObj — a dkCallback object 

_ public abstract dkQuery createQuery(String command, 

Parameters: , . , T ~ 

short commandLangType, 

qo a query object KNVPair params[ ]) throws DKException, Exception 

Returns: Creates a query object, 

a collection of the results Parameters: 
public abstract Object evaluate(DKCQExpr qe) throws C ommand-a query string 
DKException, Exception on „ 

/u commandLang — a query type 
Evaluates a query. . ... , a > 

params — additional query option in name/value pan: 
Parameters: . 

Returns: 

qe— a common query expression object a query ob j ect 

Returns: 25 public abstract dkQuery createQuery(DKCQExpr qe) 

a collection of the results throws DKException, Exception 

public abstract dkResultSetCursor execute(String command, Creates a query object, 
short commandLangType, Parameters: 

DKNVPairparams[ ]) throws DKException, Exception qe — a common query expression object 

Executes the query. 30 public abstract void addObject(dkDataObject ddo) throws 

Parameters: DKException, Exception 

j A . Adds this ddo to this datastore. 

command — a query string 

„ , Parameters: 

commandLang — a query type JJ , , , , _ . , . , 

. . , . , , . ddo — the ddo to be added to this datastore 

params-additional query option in name/value pair 35 ^ delete0bject(dkData0bject ddo) throws 

Returns: DKException, Exception 

resultSetCursor which represents a datastore cursor. Deletes this ddo from this datastore. 

public abstract dkResultSetCursor execute(dkQuery query) Parameters' 

throws DKException, Exception ^ ddo _ the ^ to be deleted from ^ datastQre 

Executes the query. public abstract void retrieveObject(dkDataObject ddo) 

Parameters: throws DKException, Exception 

qo — a query object Retrieves this ddo from this datastore. 

Returns: Parameters: 

45 

resultSetCursor which represents a datastore cursor. ddo — the ddo to be retrieved from this datastore 

public abstract dkResultSetCursor execute(DKCQExpr qe) P ublic abstract void updateObject(dkDataObject ddo) 

throws DKException, Exception throws DKException, Exception 

Executes the query. Updates this ddo in this datastore. 

Parameters: 50 Parameters: 

. • , ddo — the ddo to be updated in this datastore 
qe — a common query expression object , , . , ^ . , "!r . „ 

„ public abstract void commit/ ) throws DKException, Excep- 

Returns: tion 

resultSetCursor which represents a datastore cursor. Commits a datastore transaction, 

public abstract void executeWithCallback(dkQuery qo, 55 public abstract void rollback( ) throws DKException, 
dkcallback callbackObj) throws DKException, Exception Exception 

Executes the query with callback function. Rolls back a datastore transaction. 

Parameters: public abstract boolean isConnected( ) throws Exception 

qo^a query object 60 checks t0 see if ^ dataslore * connected. 
callbackObj— a dkCallback object Returns: 

public abstract void executeWithCallbackfString command, true tf connected 

k pubhc abstract Suing datastorename( ) throws Exception 

s ort commandLangType, ^ e(s ^ name 0 f this datastore object. Usually it repre- 

DKNVPairparams[ ], 6S sents a datastore source's server name, 
dkcallback callbackObj) throws DKException, Exception Returns: 
Executes the query with callback function. datastore name 
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public abstract String datastoretype( ) throws Exception public abstract dkcollection listEatities( ) throws 

Gets the datastore type for this datastore object. DKException, Exception 

Returns: Gets a ^ °f enu t* es fr° m persistent datastore. 

datastore type Returns: 

public abstract DKHandle connection( ) throws Exception a collection of entity defs 

Gets the connection handle for a datastore. Throws: DKException 

Returns: if error occurs 

connection handle public abstract dkcollection listSearchableEntities( ) throws 

public abstract DKHande handle(String type) throws Excep- io DKException, Exception 

tion public abstract String[ ] HstEntityNames( ) throws 

Gets a datastore handle. DKException, Exception 

Parameters* ^ ets a ^ st °^ en ^y names from persistent datastore 

type — type of datastore handle wanted ^ R cnarns * 

Returns" m °^ ent ^y names 

- . „ Throws: DKException 
a datastore handle 

public abstract String userName( ) throws Exception l error occurs _ _ „ 

* „ , - , . t . • public abstract StringT ] hstSearchableEnUtyNames( ) 

Gets the user name for this datastore object. ^ DKExceptioilj Exception 

Returns: public abstract dkcollection listEntityAttrs(String 

user name entityName) throws DKException, Exception 

public abstract dkcollection listDataSources( ) throws Gets a list of attributes for a given entity name. 

DKException, Exception Parameters: 

list the available datastore sources that can be used to 25 entityName— name of entity to retrieve attributes for 

connect with. Rcturns: 

Returns: a dkCollection of dkAttrDef objects 

a collection of server defs Throws: DKException 

public abstract String ] listDataSourceNames( ) throws jf ^ ^ n ^ ^ ml ^ 

DKException, Exception pM[c Suing[ ] listEDtityAttrNames(String 

Lists the available datastore source names that can be entityName) throws DKException, Exception 

used to connect with. Gets ft ^ of attribute names for a ^ yQn entity name 

Returns: Parameters: 

an array of server names 35 entityName — name of entity to retrieve attribute names 

public abstract Object listServers( ) throws DKException, f or 

E* 0 ^ 0 " Returns: 

Lists the available datastore sources that can be used to m of names 

connect with. Note: listservers( ) is deprecated. Replace _ 

bylistDataSources. 40 Throws: DKException 

Returns' ^ ^ e ent ^y name does not exist 

public abstract dkDatastoreDef datastoreDef( ) throws 

a collection of server definitions DKException; Exception 

&e Also: Gets datastore definition 

ListDataSources 45 Returns: 

public abstract Object listSchema( ) throws DKException, the meta . data (dkDatastoreDef) of this datastore 

Exception public abstract String registerMapping(DKNVPair 

List the entities that belong to this datastore. Note: sourceMap) throws DKException, Exception 

iistSchema( ) is deprecated. Replace by listEntities. Registers mapping information to this datastore 

Returns: 50 Parameters: 

an object that contains the schema sourceMap— source name and mapping 

See Also: Returns: 

listEntities the mapping name for the mapping information 

public abstract Object listSchemaAttributes(String 55 public abstract void unRegisterMapping(String 

schemaEntry) throws DKException, Exception mappingName) throws DKException, Exception 

List the attributes that belong to a schema Note: Unregisters mapping information for this datastore 

listSchemaAttributes( ) is deprecated. Replace by lis- Parameters: 

tEntityAttributes. . KT . - 

J mappingName — name of the mapping information 

Parameters: public a t, stract String[ ] listMappingNames( ) throws 

schemaEntry— the name of the schema, DKException, Exception 

Returns: Gets the list of the register mappings for this datastore 

an object that contains the attributes that belong to this Returns: 

schema 65 ^ arrav 0 f register mapping objects' names 

See Also: public abstract dkSchem a Mapping getMapping(String 

listEntityAttrs mappingName) throws DKException, Exception 
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Gets mapping information for this datastore Returns: 

Parameters: an array of extension objects' names 

mappingName— name of the mapping information public abstract DKDDO createDDO(String objectType, 

Returns: i Q t Flags) throws DKException, Exception 

the schema mapping object Creates a new DDO with object type, properties and 

public abstract dkextension getExtension(String attributes set for a given backend server. 

extensionName) throws DKException, Exception Parameters: 

Gets the extension object from a given extenstion name. objectType — the object type user wants to create Flags — 

Parameters: 10 *° indicate various options to specify more detail char- 

extensionName— name of the extension object. acteristics of the DDO to create. For example, it may be 

~ A a directive to create a document DDO, a folder, etc. 
Returns: 

, . , Returns: 
extension object. 

public abstract void addExtension(String extensionname, 15 ^newDDOof the given object type with all the properties 

dkExtension extensionObj) throws DKException, Exception and attnbutcs sct > 50 ^ the user only need to set the 

AJJ . . , . attribute values 

Adds a new extension object. ^ Q ^ changePassword(Stlillg ^ erW> 

Parameters: String oldPwd, 

extensionname — name of new extension object c . . „„ T n.„A\ *i „.„ iwt? ** r? 

J 20 String newPwd) throws DKException, Exception 

extensionObj— the extension object to be set pilblic abs tract void destroy( ) throws DKException, Excep- 

pubtic abstract void removeExtension(String ^ on 

extensionName) throws DKException, Exception _ 4 — . 

. . . , . Destroys datastore and performs datastore cleanup if 

Removes an existing extension object needed 

Parameters: 25 2. Federated Datastore 

extensionname— name of extension object to be removed In mc pre f e rred embodiment, the federated datastore takes 

public abstract String[ ] listExtensionNames( ) throws quer y strings expressed in a federated query language. 

DKException, Exception ^ example class definition for DatastoreFederated is 

Gets the list of extension objects' names set forth below. 



DKDatastoreFed.java 

package com.ibm.mm.sdk.server; 

public class DKDatastoreFed extends dkAbstractDataStore 
implements DKCoostantFed, 
DKConstant, 
DKMessageldFed, 
DKMessageld, 
dkFederation, 
j ava.io .Serializable 

{ 

public dkCollection listEntities( ) throws DKException, Exception 
public String[ ] listEntityNames( ) throws DKException, Exception 
public String[ ] lislTextEntityNames( ) throws DKException, Exception 
public Stringj ] listParmEntityNames( ) throws DKException, Exception 
public dkCollection listEntityAttrs(String entityName) throws DKException, Exception 
public String[ ] listEntityAttrNames(String entityName) throws DKException, Exception 
public String iegisterMapping(DKNVPair sourceMap) throws DKException, Exception 
public void unRegisteiMapping(String mappingName) throws DKException, Exception 
public String[ ] listMappingNames( ) throws DKException, Exception 
public dkSchemaMapping gctMapping(String mappingName) throws DKException, 
Exception 

public synchronized dkExtension getExtension(String extensionName) throws 

DKException, Exception 
public synchronized void addExtension(String extensionName, 

dkExtension extensionObj) throws DKException, Exception 
public synchronized void removeExtension(String extensionName) throws DKException, 

Exception 

public synchronized String[ ] listExtensionNames( ) throws DKException, Exception 
public DKDDO createDDO(String objectType, 

int Flags) throws DKException, Exception 
public dkCollection listSearchTemplates( ) throws DKException, Exception 
public String[ ] listSearcbTemplateNames( ) throws DKException, Exception 
public dkSearchTemplate getSearchTemplate(StringtempLateName) throws DKException, 
Exception 

T public void destioy( ) throwB DKException, Exception* 

public synchronized string addRemoveCursor (dkResultSetCursar iQut int action) 

throws DKException, Exception 
public dkDatastore datastoreByServerName (String dsType, String dsName) 

throws DKException, Exception 
public void changeP ass ward (String serverName, 
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-continued 



String user Id, 
String oldPwd, 
String newPwd) 

throws DKException, Exception 
public void requestConnection (String serverName, 

String uscrld, 

String passwd, 

String connectString) 

throws DKException, Exception 
public void excludeServer (Sting serverName, String templateName) 

throws DKException, Exception 
public boolean isServerExcluded (String serverName, String templateName) 

throws DKException, Exception, java.rmi.RemoteException 
public Stringf ] listExdudcdServcrs(String templateName) throws DKException, Exception 
public void clearExchadedServers (String templateName) throws DKException, Exception 



The following methods are part of the federated datastore 
class: 20 
public DKDatastoreFed( ) throws DKException, Exception 

Constructs default Federated Datastore. 
public DKDatastoreFed(String configuration) throws 
DKException, Exception 

Constructs default Federated Datastore. 25 
public void connect(String datastore_name, 

String user_name, 

String authentication, 

String connect__string) throws DKException, Exception 30 
Establishes a connection to a federated datastore. 
Parameters: 

datastore_name — federated datastore name 

user_name — userid to logon to this federated datastore 35 

authentication — password for this user„name 

connect_jstring — additional information string 

Throws: DKException 

if either: 

40 

datastore__name, user_name, or authentication is null or 

if error occurs in the federated datastore 
Overrides: 

connect in class dkAbstractDatastore 
public void disconnect ) throws DKException, Exception 45 
Disconnects from the federated datastore. 
Throws: DKException 
if unable to disconnect from server. 

Overrides: 50 
disconnect in class dkAbstractDatastore 
public Object getoption(int option) throws DKException 
Gets defined datastore option 
Parameters: 

55 

option — an option id 
Returns: 

the value for the given option 
Throws: DKException 

if option is not set 60 
Overrides: 

getOption in class dkAbstractDatastore 
public void setOption(int option, Object value) throws 
DKException 65 

Sets the given "option" with a specific "value". 

Parameters: 



option — an option id 

value — the value for the "option" 

Throws: DKException 

if option/value is invalid 

Overrides: 

setOption in class dkAbstractDatastore 
public Object evaluate(String command, 
short commandLangType, 

DKNVPairparamsf ]) throws DKException, Exception 
Evaluates a query and returns the result as a dkQuery- 

ableCollection object. 
Parameters: 

command — a query stirring that represent the query cri- 
teria 

commandLangType — a query language type, for 
Federated, it will be DK_FEDERATED_QL_TYPE 
params — a name/value pairs list 
Returns: 

a query result collection 

Throws: DKException 

if "command" argument is null 

Overrides: 

evaluate in class dkAbstractDatastore 
public Object evaluate(dkQuery query) throws 
DKException, Exception 

Evaluates a query and returns the result as a dkQuery- 
ableCollection. 

Parameters: 

query — a given query object 
Returns: 

a query result collection 
Throws: DKException 

if the "query" input is null or not of federated query type. 
Overrides: 

evaluate in class dkAbstractDatastore 
public Object evaluate(DKCQExpr qe) throws 
DKException, Exception 

Evaluates a query. 

Parameters: 

qe — a common query expression object 
Returns: 

a collection of the results 
Throws: DKException 
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if common query expression object is invalid 
Overrides: 

evaluate in class dkAbstractDatastore 
public dkResultSetCursor execute(String command, 
short commandLangType, 

DKNVPairparams[ ]) throws DKException, Exception 
Executes a command query of the federated datastore and 

returns a result set cursor. 
Parameters: 10 
command — a query string that represents the query cri- 
teria. 

commandLangType — a query language type, for 
Federated, it will be DK_FEDERATED_^_TYPE. 
params[ ] — a name/value pairs list. 
Returns: 

a dkResultSetCursor object. 
Throws: DKException 

if "command" is null or invalid, or "commandLangType" 

is not Federated Query type. 
Overrides: 

execute in class dkAbstractDatastore 
public dkResultSetCursor execute(dkQuery query) throws 25 
DKException, Exception 

Executes a command query of the federated datastore and 
returns a result set cursor. This method takes a Feder- 
ated query object as an argument. 
Parameters: 30 
query — a federated dkQuery object 
Returns: 

a dkResultSetCursor object 

Throws: DKException 35 
if "query" object is null or query.qlType( ) is not 

DK_FEDERATED_QL__TYPE 
Overrides: 

execute in class dkAbstractDatastore 40 
public dkResultSetCursor execute(DKCQExpr cqe) throws 
DKException, Exception 

Executes a query expression. 

Parameters: 

cqe — a common query expression object 45 
Returns: 

resultSetCursor which represents a federated datastore 
cursor. 

Throws: DKException 50 

if "cqe*' object is invalid 

Overrides: 

execute in class dkAbstractDatastore 
public void executeWithCallback(dkQuery query, 

dkcallback callbackObj) throws DKException, Exception 

Executes a query with callback function. 

Parameters: 

query — a query object 

callbackObj— a dkCallback object 60 
Overrides: 

execute WithCallback in class dkAbstractDatastore 
public void executeWithCallback(String command, 

short commandLangType, 65 
DKNVPair params[ ], 

dkcallback callbackObj) throws DKException, Exception 
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Executes the query with callback function. 
Parameters: 

command — a query string 

commandLang — a query type 

params — additional query option in name/value pair 

callbackObj — a dkCallback object 

Overrides: 

execute WithCallback in class dkAbstractDatastore 
public void executeWithCallback(DKCQExpr cqe, 

dkcallback callbackObj) throws DKException, Exception 
Executes a query expression with callback function. 
Parameters: 

cqe — a common query expression object 
callbackObj — a dkCallback object 
Overrides: 

execute WithCallback in class dkAbstractDatastore 
public dkQuery createQuery(String command, 
short commandLangType, 
DKNVPair params[ ]) throws DKException 
Creates a federated query object. 
Parameters: 

command — a query string that represents the query cri- 
teria 

commandLangType — a query language type, it will be 

one of the 
following: 

DK_CM_TEMPLATE_QL__TYPE 

DK_CM_TEXT_QL_TYPE 

DK__CM_IMAGE_QL_TYPE 

DK_CM_PARAMETRIC_QL_TYPE 

DK_CM_COMBINED_QL_TYPE 
params[ ] — a name/value pairs list 
Returns: 

a federated dkQuery object 
Throws: DKException 
if "command" is null 
Overrides: 

createQuery in class dkAbstractDatastore 
public dkQuery create Query(DKCQExpr qe) throws DKEx- 
ception 

Creates a query object 

Parameters: 

cqe — a common query expression object 
Throws: DKException 
if "cqe" object is invalid 
Overrides: 

createQuery in class dkAbstractDatastore 
public dkcollection listDataSources( ) throws DKException 
Lists the available datastore sources that a user can 

connect to. 
Returns: 

a collection of ServerDef objects describing the servers 

Throws: DKException 

if internal error occurs from server 

Overrides: 

listDataSources in class dkAbstractDatastore 
public Stringf ] listDataSource( )throws DKException 
Gets a list of datasource names. 
Returns: 
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an array of datasource names 
Throws: DKException 

if error occurs when retrieving datasource names 
Overrides: 

listDataSourceNames in class dkAbstractDatastore 
public void ad dObject(dkData Object dataobj) throws 
DKException, Exception 

Adds a DDO object. 

Parameters: 

ddo — a Federated object to be added. 
Throws: DKException 
if error occurs during add 
Overrides: 

addObject in class dkAbstractDatastore 
public void deleteObject(dkDataObject dataobj) throws 
DKException, Exception 

Deletes a data object. 

Parameters: 

ddo — a federated DDO object to be deleted 

Throws: DKException 

if error occurs during delete. 

Overrides: 

deleteObject in class dkAbstractDatastore 
public void retrieveObject(dkDataObject dataobj) throws 
DKException, Exception 

Retrieves a data-object. 

Parameters: 

ddo — document object to be retrieved. 
Throws: DKException 
when retrieve failed. 
Overrides: 

retrieve Object in class dkAbstractDatastore 
public void updateObject(dkDataObject dataobj) throws 
DKException, Exception 

Updates a data-object. 

Parameters: 

ddo — the data-object to be updated. 

Throws: DKException 

if error occurs in the datastore 

Overrides: 

updateObject in class dkAbstractDatastore 
public void commit( ) throws DKException 
Commits all activities since the last commit. 
Throws: DKException 

is thrown since federated datastore does not support 

transaction scope for now. 
Overrides: 

commit in class dkAbstractDatastore 
public void rollbacks throws DKException 
Rolls back all activities since the last commit. 
Throws: DKException 

is thrown since Federated does not support transaction 

scope for now. 
Overrides: 

rollback in class dkAbstractDatastore 
public boolean isconnected( ) 

Checks to see if the datastore is connected 
Returns: 

true if connected, false otherwise 



10 



15 



20 



25 



35 



45 



50 



55 



60 



65 



Overrides: 

isConnected in class dkAbstractDatastore 
public DKHandle connections throws Exception Gets the 
connection handle for the datastore. 

Returns: 

the connection handle 
Overrides: 

connection in class dkAbstractDatastore 
public DKHandle handle(String type) throws Exception 
Gets a datastore handle. 
Parameters: 

type — type of datastore handle wanted 
Returns: 

a datastore handle 
Overrides: 

handle in class dkAbstractDatastore 
public String userName( ) 

Gets the user name that user used to logon to the datastore. 
Returns: 

the userid that user used to logon 
Overrides: 

userName in class dkAbstractDatastore 
public String datastoreName( ) throws Exception 

Gets the name of this datastore object. Usually it repre- 
sents a datastore source's server name. 
Returns: 
datastore name 
Overrides: 

datastoreName in class dkAbstractDatastore 
public String datastore Type( ) throws Exception 
Gets the datastore type for this datastore object. 
Returns: 
datastore type 
Overrides: 

datastoreType in class dkAbstractDatastore 
public dkDatastoreDef datastoreDef( ) throws 
DKException, Exception 

Gets datastore definition. 

Returns: 

the meta-data (dkDatastoreDef) of this datastore 
Overrides: 

datastoreDef in class dkAbstractDatastore 
public dkcollection listEntities( ) throws DKException, 
Exception 

Gets a list of federated entities from Federated server.. 
Returns: 

a collection of dkEntityDef 
Throws: DKException 
if error occurs 
Overrides: 

listEntities in class dkAbstractDatastore 
public String[ ] listEntityNames( ) throws DKException, 
Exception 

Gets a list of federated entities names from Federated 

server. 
Returns: 

an array of names 
Throws: DKException 
if error occurs 
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Overrides: 

listEntityNames in class dkAbstractDatastore 
public String[ ] listTextEntityNames( ) throws 
DKException, Exception 

Gets a list of federated text search entities names from 5 
Federated server. 

Returns: 

an array of names 

Throws: DKException 10 
if error occurs 

public String[ ] listParmEntityNames( ) throws 
DKException, Exception 

Gets a list of federated parametric search entities names 
from Federated server. 15 

Returns: 

an array of names 
Throws: DKException 

if error occurs 20 

Overrides: 

listEntityAttrs 

public dkcollection HstEntityAttrs(String entity Name) 
throws DKException, Exception ^ 

Gets a list of attributes for a given entity name. 

Parameters: 

entityName — name of entity to retrieve attributes for 
Returns: 

a dkCollection of dkAttrDef objects 30 

Throws: DKException 

if the entity name does not exist 

Overrides: 

listEntityAttrs in class dkAbstractDatastore 35 
public String[ ] listEntityAttrNames(String entityName) 
throws DKException, Exception 

Gets a list of attribute names for a given entity name. 

Parameters: 

40 

entityName — name of entity to retrieve attribute names 

for 
Returns: 

an array of attribute names 

Tnrows: DKException 45 

if the entity name does not exist 

Overrides: 

listEntityAttrNames in class dkAbstractDatastore 
public String registerMapping(DKNVPair sourceMap) 
throws DKException, Exception 50 

Registers a mapping definition to this datastore. Mapping 
is done by entities. 

Parameters: 

sourceMap — source name and mapping, a DKNVPair 55 
class with the following possible values: 
("BUFFER",): buffer_ref is a reference to a string in 
memory 

("FILE",): file_name is the name of the file containing 

the mapping 60 
("URL",): URL-address location of the mapping 
("LDAP",): LDAP file-name 

("SCHEMA",): a reference to a dkSchemaMapping 
object defining the mapping. Currently, only 
"SCHEMA" option is supported, others may be 65 
added later. 
Returns: 



541 Bl 

26 

the name of the mapping definitioo. 
Overrides: 

registerMapping in class dkbstractDatastore 
See Also: 

unRegisterM apping 
public void unRegisterMapping(String mappingName) 
throws DKException, Exception 

Unregisters mapping information from this datastore. 

Parameters: 

mappingname — name of the mapping information 
Overrides: 

unRegisterM apping in class dkAbstractDatastore 

See Also: 

registerMapping 
public String[ ] listMappingNames( ) throws DKException, 
Exception 

Gets the list of the registered mappings for this datastore. 
Returns: 

an array of registered mapping objects' names. The array 
length would be zero if there is no mapping registered. 
Overrides: 

listMappingNames in class dkAbstractDatastore 

See Also: 

registerMapping 
public dkSchemaMapping getMapping(String 
mappingName) throws DKException, Exception 

Gets mapping information from this datastore. 

Parameters: 

mappingName — name of the mapping information 
Returns: 

the schema mapping object 
Overrides: 

getMapping in class dkAbstractDatastore 

See Also: 

registerMapping 
public synchronized dkextension getExtension(String 
extensionName) throws DKException, Exception 

Gets the extension object from a given extension name. 

Parameters: 

extensionname — name of the extension object. 
Returns: 

extension object. 
Overrides: 

getextension in class dkAbstractDatastore 
public synchronized void addExtension(String 
extensionName, 

dkExtension extensionObj) throws DKException, Excep- 
tion 

Adds a new extension object. 
Parameters: 

extensionName — name of new extension object 
extensionObj — the extension object to be set 
Overrides: 

add Extension in class dkAbstractDatastore 
public synchronized void removeExtension(String 
extensionName) throws DKException, Exception 

Removes an existing extension object. 

Parameters: 

extensionName — name of extension object to be removed 
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Overrides: 

removeExtension in class dkAbstractDatastore 
public synchronized Stringf ] listExtensionNames( ) throws 
DKException, Exception 

Gets the list of extension objects' names. 

Returns: 

an array of extension objects* names 
Overrides: 

listExtensionNames in class dkAbstractDatastore 
public DKDDO createDDO(String objectType, 
int Flags) throws DKException, Exception 
Creates a new DDO with object type, properties and 

attributes set for a given backend server. 
Parameters: 

objectType — the object type 

Flags — to indicate various options and to specify more 
detailed characteristics of the DDO to create. For 
example, it may be a directive to create a document 
DDO, a folder, etc. 

Returns: 

a new DDO of the given object type with all the properties 
and attributes set, so that the user only needs to set the 
attribute values 

Overrides: 

createDDO in class dkAbstractDatastore 
public dkcollection listSearchTemplates( ) throws 
DKException, Exception 

Gets a list search templates from a federated server. 

Returns: 

a DKSequentialCollection of search templates 

Throws: DKException 

if internal datastore error occurs 
public String[ ] listSearchTemplateNames( ) throws 
DKException, Exception 

Gets a list search templates* names from a federated 
server. 

Returns: 

an array of search template names 

Throws: DKException 

if internal datastore error occurs 
public dkSearchTemplate getSearchTemplate(String 
templateName) throws DKException, Exception 

Gets a search template information from a given template 
name. 

Returns: 

dkSearchTemplate object. 
Throws: DKException 
if internal datastore error occurs 
public void destroy( ) throws DKException, Exception 
Destroys datastore — datastore cleanup if needed 
Overrides: 

destroy in class dkAbstractDatastore 
public synchronized string addRemoveCursor 
(dkResultSetCursor iCurt int action) 

throws DKException, Exception 
public dkDatastore datastoreByServerName (String dsiype, 
String dsName) 

throws DKException, Exception 

Gets a reference to the specified datastore. The datastore 
must be connected, otherwise it will return null even if one 
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is found. First, it will look in the free connection pool. If 
none found, it will look under the connection pool held by 
active cursors. 

public void changePassword (String serverName, 
5 String user Id, 
String oldPwd, 
String newPwd) 

throws DKException, Exception 
10 Changes the password of a given user Id for a specified 
server. Administrator only function. 

Parameters: 

userid — the user — id 

oldPwd — the old password 

newPwd — the new password 
public void requestConnection (String serverName, 

String userid, 

Stringpasswd, 
20 String connectString) 

throws DKException, Exception 

Requests a connection to a particular server with the given 
userid, password & connectString. 
25 Parameters: 

userid — the user Id 
passwd — the password 
connectString — the connect string to logon 
public void excludes erver (Sting serverName, String 
30 templateName) 

throws DKException, Exception 

Requests the named server to be skipped for the named 
search template. 
35 Parameters: 

serverName — a back end server name 
templateName — a search template name 
public boolean isServerExcluded (String serverName, 
String templateName) 

throws DKException, Exception, java.rmi. RemoteEx- 
ception 

Checks if the given server is in the excluded list for the 
named search template. 
45 Parameters: 

serverName — a back end server name 
templateName — a search template name 
Returns: 
50 true or false 

public String[ ] listExcludedServers(String templateName) 
throws DKException, Exception 
Lists all the excluded servers for the named search 
template 
55 Parameters: 

s — templateName — a search template name 
Returns: 

an array of server names that were excluded during search 
6Q public void clearExcludedServers(String templateName) 
throws DKException, Exception 

Clears all the excluded servers for the named search 

template 
Parameters: 

65 s — templateName — a search template name 

The following is sample syntax of a federated query 
string. However, it is to be understood that other syntax, 
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including other parameters, may be used for the federated Each native query is submitted to the corresponding 
query string without departing from the scope of the inven- native datastore for execution. Initially, the results returned 
tion. are cursors to the data in each datastore. 



PARAMETRIC„SEARCH=QENTITY»entLty_name,] 
[MAX_RESULTS=maximum_rcsult5,] 
[COND=(conditional expression)] 

[;.] 

); 

[OPnON=flCONTENT=yes_*o] 
)] 

[and_or 

TEXT_SEARCH-(COND=(text_seaich_cxpiession) 

); 

[OFnON=([SEARCH_[NDEX={search_jndex_name | (index_list) };] 
[MAX_RESULTS-maximum_resulLs; ] 
[TIME_LIMIT=time_Jimit] 

)] 

] 

[and_or 

[ MAGE_SEARCH-(COND-(i[na ge_fsearch_expressio a) 

); 

[OPTION«([SEARCH_lNDEX={search_Jist) };] 
[MAX_RESUITS-maximum_rcsults;] 
)1 

] 



There are several mechanisms for users to submit feder- 
ated queries for execution. For example, users can create a 
federated query string and pass it to a federated query object 
and then invoke an execute or evaluate method on that object 30 
to trigger the query processing. Alternatively, a user can pass 
the federated query string to the execute or evaluate method 
in the federated datastore to process the query directly. The 
query string will be parsed into a federated query canonical 
form (query expression), which is essentially a datastore 35 
neutral representation of the query. In case the input query 
comes from a graphical user interface (GUI) based 
application, the query does not need to be parsed and the 
corresponding canonical form can be directly constructed. 

The query canonical form is the input for the federated 40 
query processor module. This module will perform the 
following tasks: 

Query translation. Translates the query canonical form 
into several native queries that corresponds to each 
native datastore associated to this federated datastore. 45 
The translation information is obtained from the 
schema mapping. 
Data conversion. Converts data in the query into a native 
data type for each of the associated native datastores. SQ 
This process uses the mapping and conversion mecha- 
nisms described in the schema mapping. 
Data filtering. Filters only the relevant data during the 
construction of native queries. 



The end-result of an initial query is a federated result set 
cursor object, which is a virtal collection (i.e., at this time, 
data has not actually been retrieved) of cursors to objects in 
each of the native datastores. 

The user can retrieve the actual data using a fetch. When 
a fetch is issued for data, the data is returned by the native 
datastores to the federated query results processor module, 
which will do the following: 

Data conversion. Converts data from the native type into 
a federated type according to the mapping information. 

Data filtering. Filters the results to include only the 
requested data Result merging. Merges the results from 
several native datastores into a federated collection. 

The federated result set cursor object provides the facility 
to separate query results according to the source native 
datastores. To do such a processing, the user/application may 
either use the federated cursor to fetch data or a native 
datastore cursor to fetch data from a particular datastore. 

AFederatedQuery represents and executes queries across 
heterogeneous datastores. This query can be a combination 
of a DL parametric query, OnDemand query, and other query 
types involving supported datastores. To retrieve data from 
each datastore, the federated datastore delegates the query 
processing task to each of the native datastores. 
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DKFcderatedQuery.java 

package com.ibm.mm.sdk.commoaDKFcderatedQuery 
public class DKFederatedQuery 
extends Object 

implements dkQuciy, DKConstant, DKMessageld, Serializable 

{ 

public D KFedera ted Query (dkDatastore creator, 

String queryString) 
public DKFederatedQuery(dkDatastore creator, 
public DKFederatedQuery(DKFederatedQuery fromQuery) 
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public void picparc(DKNVPair params[ J) throws DKException, Exception 
public void execute(DKNVPair paramsj J throws DKException, Exception 
public int status ( ) 

public Object resu!t( ) throws DKException, Exception 

public dkResultSetCursor resultSetCureorf ) throws DKException, Exception 

public short qlTyP c ( ) 

public String queryString( ) 

public dkDatastore getDatastore{ ) 

public void setDatastore(dkDatastore ds) throws DKException, Exception 

public String getName( ) 

public void setName(String name) 

public int numberOfResults( ) 

}; 



15 

The following methods are part of the federated query 
class: 

public DKFederatedQuery(dkDatastore creator, 

String queryString) 20 
Constructs a Federated query. 
Parameters: 
creator — datastore 

queryString — a query string ^ 
public DKFederatedQuery(dkDatastore creator, 
DKCQExpr queryExpr) 
Constructs a Federated query 
Parameters; 

creator — datastore 30 
queryExpr — a query expression 
public DKFederatedQuery(DKFederatedQueryfromQuery) 
Constructs a Federated query from a Federated query 

object. 35 
Parameters: 

fromQuery — Federated query 
public voidprepare(DKNVPair params[ ]) throws 
DKException, Exception 

Prepares a query, * 40 

Parameters: 

params — additional prepare query option in name/value 
pair 

public void execute(DKNVPair params[ ]) throws 45 
DKException, Exception 

Executes a query. 

Parameters: 

params — additional query option in name/value pair 
public int status( ) 50 
Gets query status. 
Returns: 
query status 

public Object result( ) throws DKException, Exception 55 
Gets query result. 
Returns: 

query result in a DKResults object 
public dkResultSetCursor resultSetCursor( ) throws 
DKException, Exception 60 

Gets query result. 

Returns: 

query result in a dkResultSetCursor object 
public short qlType( ) 65 
Gets query type. 
Returns: 



query type 

public String querystring( ) 
Gets query string 
Returns: 
query string 

public dkDatastore getDatastore( ) 

Gets the reference to the owner datastore object. 
Returns: 

the dkDatastore object 

public void setDatastore(dkDatastore ds) throws 
DKException, Exception 

Sets the reference to the owner datastore object. 

Parameters: 

ds — a datastore 

public String getName( ) 

Gets query name. 
Returns: 

name of this query 
public void setName(String name) 

Sets query name. 
Parameters: 

name — new name to be set to this query object 
public int numberOfResults( ) 

Gets the number of query results. 
Returns: 

number of query results 
3. Digital Library Datastore 

DKDatastoreDL is a specific version of dkDatastore used 
to implement the Digital Library /Visual Info datastore. 
It provides Documents, Parts and Folders storage and 
retrieval mechanisms, as well as search and other 
document processing capabilities supported by Digital 
Library. An example class definition for DKDatas- 
toreDL is set forth below. 
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DKDatastoTeDL 

package rom.ibm.mm.sdkserver.DKDatastoreDL 
public class DKDatastoreDL 

extends dkAbstractDatastore 

implements DKConstantDL, DKMessagcIdDL 

{ 

public DKDatastoreDLO throws DKException, Exception 

public DKDatastoreDLfString configuration) throws DKException, Exception 

public void connect(Stiing datastore_name, 

String uscr_name, 

String authentication, 

String connect_string) throws DKException, Exception 
public void disco nnectO throws DKException, Exception 
public Object getOption(int option) throws DKException, Exception 
public void setOptionfint option, 

Object value) throws DKException, Exception 
public Object evaluate(String command, 

short commandLangType, 

DKNVPair params[]) throws DKException, Exception 
public Object evaluate(dkQuery query) throws DKException, Exception 
public Object evaluate(DKCQExpr qe) throws DKException, Exception 
public dkResultSetCursor execute(String command, 
short commandlangiypc, 

DKNVPair paramsf]) throws DKException, Exception 
public dkResultSetCursor execute(dk Query query) throws DKException, Exception 
public dkResultSetCursor execute (DKCQExpr cqe) throws DKException, Exception 
public void executeWithCallback(dkQuery query, 

dkCallback callbackObj) throws DKException, Exception 
public void executeWithCallback(String command, 

short commandLangType, 

DKNVPair params[], 

dkCallback callbackObj) throws DKException, Exception 
public void executeWithCallback(DKCQExpr qe, 

dkCallback callbackObj) throws DKException, Exception 
public dkQuery createQuery(String command, 
short commandLangType, 

DKNVPair paramsf]) throws DKException, Exception 
public dkQuery createQueiy(DKCQExpr qe) throws DKException, Exception 
public void addObject(dkDataObject ddo) throws DKException, Exception 
public void deleteObject(dkDataObject ddo) throws DKException, Exception 
public void rctrieveObject(dkDataObject ddo) throws DKException, Exception 
public void updateObject(dkData Object ddo) throws DKException, Exception 
public void moveObject(dkData Object ddo, 

String entityName) throws DKException, Exception 
public void startTransactionO throws DKException, Exception 
public void commitQ throws DKException, Exception 
public void iollbackO throws DKException, Exception 
public boolean isConnectedQ throws Exception 
public String datastorcNameO throws Exception 
public String datastoreType() throws Exception 
public DKHandle connectionO throws Exception 
public DKHandle handle(String type) throws Exception 
public DKHandle transactionConnectionQ throws DKException, Exception 
public String userNameO throws Exception 

public dkCollection listDataSourcesQ throws DKException, Exception 
public String[] listDataSourceNames() throws DKException, Exception 
public Object listServersf) throws DKException, Exception 
public Object listSchemaQ throws DKUsageError 

public Object lis tSchema Attributes (String schemaEntry) throws DKusageErroi, 

DKDatastoreAccessEiror 
public dkCollection listEntitiesQ throws DKException, Exception 
public String[] listEntity Names 0 throws DKException, Exception 
public dkCollection listEntityAttrs (String entityName) throws DKException, Exception 
public Stringt] listEntityAttrNames(String entityName) throws DKException, Exception 
public void wakeUpService(String searchEngine) throws DKException, Exception 
public void invokeSearchEnginefString searchEngine, 

String searchlndex) throws DKException, Exception 
public dkDatastoreDef datastoreDefQ 

public DKWorkFlowServiceDL create WorkFlowServiceQ throws DKException, 
Exception 

public String registerMapping(DKNVPair sourceMap) throws DKException, Exception 

public void unRegisterMapping(String mappingName) throws DKException, Exception 

public Stringf] listMappingNamesO throws DKException, Exception 

public dkschemaMapping getMapping(String mappingName) throws DKException, 

Exception 

public synchronized dkBxtension getExtension(String extensionName) throws 

DKException, Exception 
public synchronized void addExtension(String extensionName, 
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dkExtension extensionObj) throws DKExccption, Exception 
public synchronized void removeExt*nsion(String extensionName) throws DKException, 
Exception 

public synchronized String! ] listExtensioaNamesO throws DKException, Exception 
public DKDDO createDDO(String objecfiype, 

int Flags) throws DKException, Exception 
public void destroy Q throws DKException, Exception 
public boolean isCheckedOutfdkDataObject dobj) throws DKUsageError, 

DKDatastoreAccessError 
public String checkedOutUserid(dkDataObject dobj) throws DKUsageError, 

DKDatastoreAccessError 
public void urdoc±ChedcedOut(d]cDataObject dobj) throws DKUsageError, 

DKDatastoreAccessError 
public void chcckOut(dkDataObject dobj) throws DKUsageError, 
DKDatastoreAccessError 

public void checkln(dkDataObject dobj) throws DKUsageError, DKDatastoreAccessError 
public void changePassword(String userld, 
String oldPwd, 

String newPwd) throws DKException, Exception 
public synchronized dkXDO letrieveFormOverlay (String objid) throws DKException, 
Exception 

public DKCQExpr transIate(DKCQExpr cqe) throws DKException, Exception 
} 



The following methods are part of the DKDatastoreDL 
class: 

public DKDatastoreDL( ) throws DKException, Exception 

Constructs the datastore and initializes the datastore. 
public DKDatastoreDL(String configuration) throws 
DKException, Exception 

Constructs the datastore and initializes the datastore. 
public void connect(String datastore_name, 
String user _jiame, 
String authentication, 

String connect_string) throws DKException, Exception 

Connects to a datastore. 

Parameters: 

datastore_name — the datastore name used for connection 
user_name — the user name used for connection 
authentication— Ahe authentication used for connection 
connect_string — the connect sting used for connection. 

This is used to 
provide additional connection options. 
Overrides: 

connect in class dkAbstracDatastore 
public void disco one ct( ) throws DKException, Exception 
Disconnects from a datastore. 
Overrides: 

disconnect in class dkAbstractDatastore 
public Object getOption(int option) throws DKException, 
Exception 

Gets a datastore option. 
Parameters: 

option — the option identifier 

Returns: 

an option value 

Overrides: 

getOption in class dkAbstractDatastore 
public void setOption(int option, 

Object value) throws DKException, Exception 
Sets a datastore option. 



Parameters: 

option — the option identifier 
value — the option value 
Overrides: 

setOption in class dkAbstractDatastore 
public Object evaluate(String command, 
short commandLangType, 

DKNVPair params[ ]) throws DKException, Exception 

Evaluates the query. 

Parameters: 

command — a query string 

commandlang — a query type 

params — additional query option in name/value pair 

Returns: 

a collection of the results 
Overrides: 

evaluate in class dkAbstractDatastore 
public Object evaluate(dkquery query) throws 
DKException, Exception 

Evaluates the query. 

Parameters: 

query — a query object 

Returns: 

a collection of the results 
Overrides: 

evaluate in class dAbstractDatastore 
public Object evaluate(DKCQExpr qe) throws 
DKException, Exception 

Evaluates the query. 

Parameters: 

qe — a common query expression object 
Returns: 

a collection of the results 
Overrides: 

evaluate in class dkAbstractDatastore 
public dkResultSetCursor execute(String command, 
short commandLangType, 

DKNVPairparams[ ]) throws DKException, Exception 
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Executes the query. 
Parameters: 

command — a query sting 
commandlang — a query type 

params — additional query option in name/value pair 
Returns: 

resultSetCursor which represents a datastore cursor. 
Overrides: 

execute in class dkAbstractDatastore 
public dkResultSetCursor execute(dkQuery query) throws 
DKException, Exception 

Executes the query. 

Parameters: 15 

query — a query object 

Returns: 

resultSetCursor which represents a datastore cursor. 

Overrides: 20 

execute in class dkAbstractDatastore 
public dkResultSetCursor execute(DKCQExpr cqe) throws 
DKException, Exception 

Executes a query expression and returns a result set cursor 

Parameters: 25 

cqe — a common query expression object 

Returns: 

resultSetCursor which represents a datastore cursor. 
Overrides: 30 
execute in class dkAbstractDatastore 
public void executeWithCallback(dkQuery query, 

dkcallback callbackObj) throws DKException, Exception 

Executes the query with callback function. - 35 

Parameters: 

qo — a query object 

callbackObj — a dkCallback object 

Overrides: 

40 

executeWithCallback in class dkAbstractDatastore 
public void executeWithCallback(String command, 
short commandLangType, 
DKNVAPair params[ ], 

dkcallback callbackObj) throws DKException, Exception 45 

Executes the query with callback function. 

Parameters: 

command — a query string 

commandLang — a query type 50 
params — additional query option in name/value pair 
callbackObj — a dkCallback object 
Overrides: 

executeWithCallback in class dkAbstractDatastore 55 
public void executeWithCallback(DKCQExpr qe, 

dkcallback callbackObj) throws DKException, Exception 
Executes the query with callback function. 
Parameters: 

qe — a common query expression object 60 

callbackObj — a dkCallback object 

Overrides: 

executeWithCallback in class dkAbstractDatastore 
public dkQuery createQuery(String command,. 65 
short commandLangType, 

DKNVPair params[ ]) throws DKException, Exception 
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Creates a query object. 
Parameters: 

command — a query string 

commandlang — a query type 

params — additional query option in name/value pair 

Returns: 

a query object 

Overrides: 

createQuery in class dkAbstractDatastore 
public dkQuery createQuery(DKCQExpr qe) throws 
DKException, Exception 

Creates a query object. 

Parameters: 

qe — a common query expression object 
Overrides: 

createQuery in class dkAbstractDatastore 
public void addObject(dkDataObject ado) throws 
DKException, Exception 

Adds this data -object to the DL datastore. 

Parameters: 

ddo — the data-object to be added to this datastore 
Overrides: 

addObject in class dkAbstractDatastore 

See Also: 

add 

public void deleteObject(dkDataObject ddo) throws 
DKException, Exception 

Deletes this data-object from this datastore. 

Parameters: 

ddo — the data-object to be deleted from this datastore 
Overrides: 

delete Object in class dkAbstractDatastore 

See Also: 

del 

public void retrieveObject(dkDataObject ddo) throws 
DKException, Exception 

Retrieves the data-object from this datastore. 

Parameters: 

ddo — the data-object to be retrieved from this datastore 
Overrides: 

retrieveObject in class dkAbstractDatastore 

See Also: 

retrieve 

public void updateObject(dkDataObject ddo) throws 
DKException, Exception 

Updates the data-object in this datastore. 

Parameters: 

ddo — the data-object to be updated in this datastore 
Overrides: 

updateObject in class dkAbstractDatastore 

See Also: 

update 

public void moveObject(dkDataObject ddo, 

String entityName) throws DKException, Exception 
Moves the data^object from one index class to another in 

this datastore. 
Parameters: 

ddo — the data-object to be move in this datastore 
entityName — new entity name to move this data-object 
to 
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public void startTraQsaction( ) throws DKException, Excep- 
tion 

Starts a transaction 
public void commit( ) throws DKException, Exception 
Commits a datastore transaction 
Overrides: 

commit in class dkAbstractDatastore 
public void rollback( ) throws DKException, Exception 
Rolls back a datastore transaction 
Overrides: 

rollback in class dkAbstractDatastore 
public boolean isconnected( ) throws Exception 

Checks to see if the datastore is connected, ' 
Returns: 

true if connected 
Overrides: 

isConnected in class dkAbstractDatastore 
public String datastoreName( ) throws Exception 

Gets the name of this datastore object. Usually it repre- 
sents a datastore source's server name. 

Returns: 

datastore name 

Overrides: 

datastoreName in class dkAbstracDatastore 
public String datastoreType( ) throws Exception 
Gets the datastore type for this datastore object 
Returns: 
datastore type 
Overrides: 

datastoreiype in class dkAbstractDatastore 
public DKHandle connection( ) throws Exception 
Gets the connection handle for a datastore 
Returns: 

connection handle 
Overrides: 

connection in class dkAbstractDatastore 
public DKHandle handle(String type) throws Exception 
Gets a datastore handle 
Parameters: 

type — type of datastore handle wanted 
Returns: 

a datastore handle 
Overrides: 

handle in class dkAbstractDatastore 
public DKHandle transactionConnection( ) throws 
DKException, Exception 

Gets the transaction handle for a datastore 

Returns: 

transaction handle 
public String userName( ) throws Exception 
Gets the user name for this datastore object 
Returns: 
user name 
Overrides: 

userName in class dkAbstractDatastore 
public dkCollection listDataSources( ) throws 
DKException, Exception 

List the available datastore sources that can be used to 
connect with. 



Returns: 

a collection of server definitions 
Overrides: 

5 listDataSources in class dkAbstractDatastore 

public String[ ] HstDataSourceNames( ) throws 
DKException, Exception 

Lists the available datastore source names that can be 
used to connect with. 
10 Returns: 

an array of server names 
Overrides: 

listDataSource Names in class dkAbstractDatastore 
15 public Object listServers( ) throws DKException, Exception 

Lists the available datastore sources that can be used to 
connect with. Note: listservers( ) is deprecated. Replace 
by listDataSources. 

Returns: 

20 a collection of server definitions 
Overrides: 

listServers in class dkAbstractDatastore 
See Also: 
25 listDataSources 

public Object listschema( ) throws DKUsageError 

Lists the entities that belong to this datastore. Note: 
listschema( ) is deprecated. Replace by listentities. 
30 Returns: 

an object that contains the schema 
Overrides: 

listSchema in class dkAbstractDatastore 
See Also: 
listEntities 

public Object listSchemaAttributes(String schemaEntry) 
throwsDKUsageError, 
DKDatastoreAccessError 
40 Lists the attributes that belong to a schema Note: 
listSchemaAttributes( ) is deprecated. Replace by lis- 
tEntityAttributes. 
Parameters: 

schemaEntry — the name of the schema 
Returns: 

an object that contains the attributes that belong to this 

schema 
Overrides: 

50 listSchemaAttributes in class dkAbstractDatastore 
See Also: 
listEntityAttrs 

public dkCollection listEntities( ) throws DKException, 
55 Exception 

Gets a list of entities from persistent datastore 
Returns: 

a collection of entity defs 
so Throws: DKException 
if error occurs 
Overrides: 

listEntities in class dkAbstractDatastore 
65 public String[ ] listEntityNames( ) throws DKException, 
Exception 

Gets a list of entity names from persistent datastore 
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Returns: 

an array of entity names 
Throws: DKException 
' if error occurs 
Overrides: 

listEntityNames in class dkAbstractDatastore 
public dkcollection HstEntityAttrs(String entityName) 
throws DKException, Exception 

Gets a list of attributes for a given entity name. 

Parameters: 

entityName — name of entity to retrieve attributes for 
Returns: 

a dkCollection of dkAttrDef objects 
Throws: DKException 
if the entity name does not exist 
Overrides: 

listEntityAttrs in class dkAbstractDatastore 
public String[ ] listEntityAttrNames(String entityName) 
throws DKException, Exception 

Gets a list of attribute names for a given entity name. 

Parameters: 

entityName — name of entity to retrieve attribute names 

for 
Returns: 

an array of attribute names 
Throws: DKException 
if the entity name does not exist 
Overrides: 

listEntityAttrNames in class dkAbstractDatastore 
public void wake Up Service (String searchEngine) throws 
DKException, Exception 
Wakes up a user exit to process search index request. 
Note: wakeUpService( ) is deprecated. Replace by 
invokeSearchEngine, 
Parameters: 

searchengine — search engine name (SM) 
See Also: 

invokeSe archEngine 
public void invokeSearchEngine(String searchEngine, 
String searchlndex) throws DKException, Exception 
Invokes a user exit to process search index request. 
Parameters: 

searchEngine — search engine name (ie SM or QBIC) 
searchlndex— search index (ie TM-TMINDEX or 
QBICDB-QBICCAT-QBICSRV) 
public dkDatastoreDef datastoreDef( ) 
Gets datastore definition 
Returns: 

the meta-data (dkDatastoreDef) of this datastore 
Overrides: 

datastoreDef in class dkAbstractDatastore 
pub'lic DKWorkFlowServiceDL create\VorkFlowService( ) 
throws DKException, Exception 

Gets work flow service 

Returns: 

the a work flow service for this datastore 
public String registerMapping(DKNVPair sourceMap) 
throws DKException, Exception 65 

Registers a mapping definition to this datastore. Mapping 
is done by entities. 
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Parameters: 

sourceMap — source name and mapping, a DKNVPair 
class with the following possible values: 

("BUFFER",): buffer_ref is a reference to a string in 
memory 

("FILE",): file_jiame is the name of the file containing 

the mapping 
("URL",): URLr address location of the mapping 
("LDAP",): LDAP file-name 

"SCHEMA",): a reference to a dkSchemaMapping object 
defining the mapping. Currently, only "SCHEMA" 
option is supported, others may be added later. 

Returns: 

the name of the mapping definition. 
Overrides: 

registerMapping in class dkAbstractDatastore 
See Also: 

unRegisterMapping 
public void unRegisterMapping(String mappingName) 
throws DKException, Exception 

Unregisters mapping information from this datastore. 

Parameters: 

mappingName — name of the mapping information 
Overrides: 

unRegisterMapping in class dkAbstractDatastore 

See Also: 

registerMapping 
public Stringf ] HstMappingNames( ) throws DKException, 
Exception 

Gets the list of the registered mappings from this datas- 
tore. 
Returns: 

an array of registered mapping objects' names 
Overrides: 

listMappingNames in class dkAbstractDatastore 

See Also: 

registerMapping 
public dkSchemaMapping getMapping(String 
mappingName) throws DKException, Exception 

Gets a mapping information from this datastore. 

Parameters: 

mappingName — name of the mapping information 
Returns: 

the schema mapping object 
Overrides: 

getMapping in class dkAbstractDatastore 

See Also: 

registerMapping 
public synchronized dkExtension getExtension(String 
extensionName) throws DKException, Exception 

Gets the extension object from a given extenstion name. 

Parameters: 

extensionname — name of the extension object. 
Returns: 

extension object. 
Overrides: 

getextension in class dkAbstractDatastore 
public synchronized void addExtension(String 
extensionName, 
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dkExtension extensionObj) throws DKException, Excep- public void unlockCheckedOut(dkDataObject dobj) throws 

tion DKUsageError, 
Adds a new extension object. 
Parameters: 

extensionname— name of new extension object 

extensionObj — the extension object to be set Parameters: 

Overrides: dobj — data object (document or folder item) 

addextension in class dkAbstractDatastore public void checkOut(dkDataObject dobj) throws 

public synchronized void removeExtension(String 10 DKUsageErr or, DKDatastoreAccessError 
extensiooName) throws DKException, Exception 

Removes an existing extension object Checks out document or folder item from datastore 

Parameters: Parameters: 

extensionName — name of extension object to be removed 15 dobj — data object (document or folder item) 

Overrules: public void checkln(dkDataObject dobj) throws 

removeExtension in class dkAbstractDatastore DKUsageError, DKDatastoreAccessError 
public synchronized Stringf ] listExtensionNames( ) throws 

DKException, Exception Checks in document or folder item from datastore 

Gets the list of extension objects' names 20 Parameters: 

Returns: dobj— data object (document or folder item) 

an array of extension objects* names „ . 

Overrides* public void changePassword(Stnng userid, 

listExtensionNames in class dkAbstractDatastore 25 String oldPwd, 

public DKDDO createDDO(String objectiype, string DCW Pwd) throws DKException, Exception 

int Flags) throws DKException, Exception Changes LS user password 
Creates a new DDO with object type, properties and 

attributes set for a given backend server. Overrides: 

Parameters: changepassword in class dkAbstractDatastore 

objectType— the object type user wants to create pu bUc synchronized dkXDO retrieveFormOverlay(String 

Flags — to indicate various options to specify more objid) throws DKException, Exception 
detailed 

characteristics of the DDO to create. For example, it may 35 Retrieves the form overlay object 

be a directive to create a document DDO, a folder, etc. Parameters: 

Returns: id — the id string to retrieve the object 

a new DD 0 of the given obj ect type with all the properties Returns: 

L t ...... 1 . , 40 the form overlay xdo object 

attnbutes set, so that the user only need to set the attribute 

values public void moveObject (dkDataObject ddo, String 

Overrides: entityName) throws DKException, Exception 

createDDO in class dkAbstractDatastore Moves the data object from one index class to another, 

public void destroy( ) throws DKException, Exception 45 

Destroys datastore — datastore cleanup if needed 

Overrides: ddo — data object to be moved 

destroy in class dkAbstractDatastore entityName — target index class for this data object 

DKUsa!j£r isChecked0ut ( dkData0b j ect dob j> throws 50 public DKCQExpr tra Q slate(DKCQExpr cqe) throws 



Parameters: 



DKException, Exception 
DKD atastoreAccessError 

Checks whether a document or folder item is checked out Translates a query expression into a native query expres- 

from datastore S10n processable by this datastore. 

Parameters: ss Parameters: 

dobj-data object (document or folder item) cq( ^_ thc ^ compound qucry expression 

Returns: „ ^ 

i Returns: 

a boolean indicating if it is checked out or not 

public String checkedOutUserid(dkDataObject dobj) throws 60 a translated q ucr y expression or null if the expression is 

DKUsageError, DKDatastoreAccessError invalid 

Lists the userid who checked out the document or folder 4. OBIC Datastore 

Parameters* 

r,, . ^ DKDatastoreQBIC is a specific version of dkDatastore 

dobj-data object (document or folder item) 65 ^ to implemerjt the QB]C data store. An example 

Returns: class definition for DKDatastoreQBIC is set forth 

a userid or empty string (i.e., not checked out) below. 
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DKDatastoreQB[C 

package com.ibm.mm.sdk.servei.DKDatastOreQBIC 
public class DKDatastoreQBIC 

extends dkAbstractDatastore 

implements DKCorstantDL, DKMessagcIdDL 

{ 

public DKDatastOreQBICO throws DKException, Exception 

public DKDatastoreQB[C(String configuration) throws DKException, Exception 

public void connects tring datastore_aame, 

String useT_name ) 

String authentication, 

String connect_string) throws DKException, Exception 
public void disco nnect() throws DKException, Exception 
public Object getOptton(int option) throws DKException, Exception 
public void setOption(int option, 

Object value) throws DKException, Exception 
public Object evaluate(String command, 

short commandLangType, 

DKNVPair params[J) throws DKException, Exception 
public Object evahiate(dkQuery query) throws DKException, Exception 
public Object evahiate(DKCQExpr qe) throws DKException, Exception 
public dkResultSetCursor execute(String command, 
short commandLangType, 

DKNVPair paramsfj) throws DKException, Exception 
public dkResultSetCursor execute(dkQuery query) throws DKException, Exception 
public dkResultSetCursor execute(DKCQExpr qe) throws DKException, Exception 
public void execute WithCallback(dkQueTy query, 

dkCallback callbackObj) throws DKException, Exception 
public void executewithCallback(String command, 

short commandLangType, 

DKNVPair params[], 

dkCallback callbackObj) throws DKException, Exception 
public void execute WithCallback(DKCQExpr qe, 

dkCallback callbackObj) throws DKException, Exception 
public dkQuery createQueiy(String command, 
short commandLangType, 

DKNVPair params[J) throws DKException, Exception 
public dkQuery createQuexy(DKCQExpr qe) throws DKException, Exception 
public void addObject(dkDataObject ddo) throws DKException, Exception 
public void deleteObject(dkDataObject ddo) throws DKException, Exception 
public void retrieveObject(dkDataObject ddo) throws DKException, Exception 
public void updateObject(dkDataObject ddo) throws DKException, Exception 
public void commitO throws DKException, Exception 
public void rollbackO throws DKException, Exception 
public boolean isConnected0 throws Exception 
public String datastoreNameO throws Exception 
public String datastoreType() throws Exception 
public DKHandle connectiooQ throws Exception 
public DKHandle handle(String type) throws Exception 
public String userNameQ throws Exception 

public dkCollection listDataSourcesO throws DKException, Exception 
public String[] listDataSourceNamesO throws DKException, Exception 
public Object listServers0 throws DKException, Exception 
public Object listSchemaO throws DKException, Exception 

public Object listSchemaAttributes(String schemaEntry) throws DKException, Exception 

public dkCollection HstEntitiesQ throws DKException, Exception 

public String[] listEntity Names 0 throws DKException, Exception 

public dkCollection listEntityAttrs (String entity Name) throws DKException, Exception 

public String[ ] listEntity AttiNames(String entityNamc) throws DKException, Exception 

public void destroyO throws DKException, Exception 

public void createDatabase(String database__name) throws DKException, Exception 
public void deleteDatabasc(Suing database__name) throws DKException, Exception 
public void createCatalog(String database_name, 

String catalog_name) throws DKException, Exception 
public void deleteCatalog(String database_name, 

String catalog_name) throws DKException, Exception 
public void openCatalog(String database_name, 

String catalog_name) throws DKException, Exception 
public void closeCatalogO throws DKException, Exception 
public void addColorFeatureO throws DKException, Exception 
public void addDrawFeature{) throws DKException, Exception 
- public void addColorHisiogramFeatureO throws DKException, Exception 
public void addTextureFeature() throws DKException, Exception 
public void addFeature{int featureSelection, 

boolean bReCatalog) throws DKException, Exception 
public void removeColorFeatureQ throws DKException, Exception 
public void removeDrawFeatureO throws DKException, Exception 
public void removeColorHistogramFeatiireQ throws DKException, Exception 
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public void removeTexturcFeatureO throws DKException, Exception 
public void processImages(DKJmageRecordQBIC imageListf], 

int count) throws DKException, Exception 
public synchronized void queueImagcs(DKImageRecordQBIC unageListf], 

int count) throws DKException, Exception 
public void processImageQueueO throws DKException, Exception 
public void reCatalogImages(int featureSelectionlist) throws DKException, Exception 
public Object listDatabasesfJ throws DKException, Exception 
public Object listCatalogsO throws DKException, Exception 
public Object listCata!ogs(String database_name) throws DKException, Exception 
public Object liatFeaturesO throws DKException, Exception 
public Object listColorlmagesO throws DKException, Exception 
public Object listHistogramlmagesQ throws DKException, Exception 
public Object listDrawImagcs() throws DKException, Exception 
public Object listTextureImages() throws DKException, Exception 
public String databaseNamcQ throws DKException, Exception 
public String catalogNameO throws DKException, Exception 
public String getLibServerNameQ throws DKException, Exception 
public dkDatastoreDef datastoreDefO throws DKException, Exception 
public String registerMapping(DKNVPair sourceMap) throws DKException, Exception 
public void unRegLsterMapping(String mappingName) throws DKException, Exception 
public String!] listMappingNamesO throws DKException, Exception 
public dkSchemaMapping getMapping(String mappingName) throws DKException, 
Exception 

public synchronized dkExtension getExtension(String extensionName) throws 

DKException, Exception 
public synchronized void addExtension(String extensionName, 

dkExtension extensionObj) throws DKException, Exception 
public synchronized void reoioveExtcnsion(Strin.g extensionName) throws DKException, 

Exception 

public synchronized String[] listExtensionNamesQ throws DKException, Exception 
public DKDDO createDDO (String objectTVpc, 

int Flags) throws DKException, Exception 

} 



The following methods are part of the DKDatastoreQBIC 
class: 

public DKDatastoreQBICO throws DKException, Excep- 35 
tion 

Constructs the datastore and initializes the datastore, 
public DKDatastoreQBIC(String configuration) throws 
DKException, Exception 

Constructs the datastore and initializes the datastore. 
public void connect(String datastore_name, String user__ 
name, String authentication, String connect_string) throws 
DKException, Exception 

Connects to a datastore. 45 

Parameters: 

datastore_nane — the datastore name used for connection 
user __name — the user name used for connection 
authentication — the authentication used for connection 
connect_string — the connect string used for connection. 

This is used to 
provide additional connection options. 
Overrides: 

connect in class dkAbstractDatastore 55 
public void disconnect ) throws DKException, Exception 
Disconnects to a datastore. 
Overrides: 

disconnect in class dkAbstractDatastore 
public Object getOption(int option) throws DKException, 60 
Exception 

Gets a datastore option. 

Parameters: 

option — the option identifier 65 

Returns: 

an option value 



Overrides: 

getOption in class dkAbstractDatastore 
public void setOption(int option, 

Object value) throws DKException, Exception 

Sets a datastore option. 

Parameters: 

option — the option identifier 
value — the option value 
Overrides: 

setOption in class dkAbstractDatastore 
public Object evaluate(String command, 
short commandLangType, 

DKNVPair params[ ]) throws DKException, Exception 

Evaluates the query. 

Parameters: 

command — a query string 

commandLang — a query type 

params — additional query option in name/value pair 

Returns: 

a collection of the results 
Overrides: 

evaluate in class dkAbstractDatastore 
public Object evaluate(dkQuery query) throws 
DKException, Exception 

Evaluates the query. 

Parameters: 

query — a query object 

Returns: 

a collection of the results 
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Overrides: 

evaluate in class dkAbstractDatastore 
public Object evaluate(DKCQExpr qe) throws 
DKException, Exception 

Evaluates the query. 5 

Parameters: 

qe — a common query expression object 
Returns: 

a collection of the results 10 
Overrides: 

evaluate in class ckAbstractDatastore 
public dkResultSetCursor execute(String command, 

short commandLangType, 15 
DKNVPairparams[ ]) throws DKException, Exception 
Executes the query. 
Parameters: 

command — a query string 2Q 

commandLang — a query type 

params — additional query option in name/value pair 

Returns: 

resultSetCursor which represents a datastore cursor. 
Overrides: 

execute in class dkAbstractDatastore 
public dkResultSetCursor execute(dkQuery query) throws 
DKException, Exception 

Executes the query. 30 

Parameters: 

query — a query object 

Returns: 

resultSetCursor which represents a datastore cursor. 35 
Overrides: 

execute in class dkAbstractDatastore 
public dkResultSetCursor execute(DKCQExpr qe) throws 
DKException, Exception 

Executes the query. 40 

Parameters: 

qe — a common query expression object 
Returns: 

resultSetCursor which represents a datastore cursor. 45 
Overrides: 

execute in class dkAbstractDatastore 
public void executeWithCallback(dkQuery query, 

dkcallback callbackObj) throws DKException, Exception 50 

Executes the query with callback function. 

Parameters: 

qo — a query object 

callbackObj — a dkCallback object ^ 
Overrides: 

execute WithCallback in class dkAbstractDatastore 
public void executeWithCallback(String command, 
short commandLangType, 

DKNVPair paramsf ], so 
dkCallback callbackObj) throws DKException, Excep- 
tion 

Executes the query with callback function. 
Parameters: 

command — a query string 
commandLang — a query type 
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params — additional query option in name/value pair 

callbackObj — a dkCallback object 

Overrides: 

execute WithCallback in class dkAbstractDatastore 
public void executeWithCallback(DKCQExpr qe, 

dkcallback callbackObj) throws DKException, Exception 
Executes the query with callback function. 
Parameters: 

qe — a common query expression object 
callbackObj — a dkCallback object 
Overrides: 

execute WithCallback in class dkAbstractDatastore 
public dkQuery createQuery(String command, 
short commandLangType, 

DKNVPairparams[ ]) throws DKException, Exception 

Creates a query object. 

Parameters: 

command — a query string 

commandLang — a query type 

params — additional query option in name/value pair 

Returns: 

a query object 

Overrides: 

createQuery in class dkAbstractDatastore 
public dkQuery create Query(DKCQExpr qe) throws 
DKException, Exception 

Creates a query object. 

Parameters: 

qe — a common query expression object 
Overrides: 

createQuery in class dkAbstractDatastore 
public void addObject(dkDataObject ddo) throws 
DKException, Exception 

Adds this ddo to this datastore. 

Parameters: 

ddo — the ddo to be added to this Datastore 
Overrides: 

addObject in class dkAbstractDatastore 
public void deleteObject(dkDataObject ddo) throws 
DKException, Exception 

Deletes this ddo from this datastore. 

Parameters: 

ddo — the ddo to be deleted from this Datastore 
Overrides: 

deleteObject in class dkAbstractDatastore 
public void retrieveObject(dkDataObject ddo) throws 
DKException, Exception 

Retrieves this ddo from this datastore. 

Parameters: 

ddo — the ddo to be retrieved from this Datastore 
Overrides: 

retrieve Object in class dkAbstractDatastore 
public void updateObject(dkDataObject ddo) throws 
DKException, Exception 

Updates this ddo in this datastore. 

Parameters: 

ddo — the ddo to be updated in this Datastore 
Overrides: 

updateObject in class dkAbstractDatastore 
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public void commit( ) throws DKException, Exception 
Commits a datastore transaction 
Overrides: 

commit in class dkAbstractDatastore 
public void rollback( ) throws DKException, Exception 
Rolls back a datastore transaction 
Overrides: 

rollback in class dkAbstractDatastore 
public boolean isconnected( ) throws Exception 
Checks to see if the datastore is connected. 
Returns: 

true if connected 
Overrides: 

is Connected in class dkAbstractDatastore 
public String datastoreName{ ) throws Exception 

Gets the name of his datastore object. Usually it repre- 
sents a datastore source's server name. 

Returns: 

datastorename 

Overrides: 

datastorename in class dkAbstractDatastore 
public String datastoreTypeO throws Exception 
Gets the datastore type for this datastore object 
Returns: 
datastore type 
Overrides: 

datastoreType in class dkAbstractDatastore 
public DKHandle connection( ) throws Exception 
Gets the connection handle for a Datastore 
Returns: 

connection handle 
Overrides: 

connection in class dkAbstractDatastore 
public DKHandle handle(String type) throws Exception 
Gets a datastore handle 
Parameters: 

type — type of datastore handle wanted 
Returns: 

a datastore handle 
Overrides: 

handle in class dkAbstractDatastore 
public String userName( ) throws Exception 
Gets the user name for this datastore object 
Returns: 
user name 
Overrides: 

userName in class dkAbstracIDatastore 
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public dkcollection HstDataSources( ) throws DKException, 55 Exception 



Returns: 

an array of server names 
Overrides: 

listDataSourceNames in class dkAbstractDatastore 
public Object listServers( ) throws DKException, Exception 
Lists the available datastore sources that can be used to 

connect with. Note: listservers( ) is deprecated. Replace 

by listDatasources. 
Returns: 

a collection of server definitions 
Overrides: 

listservers in class dkAbstractDatastore 
See Also: 
listDataSources 
public Object listschema( ) throws DKException, Exception 
lists the entities that belong to this datastore. Note: 

listschema( ) is deprecated. Replace by listEntities. 
Returns: 

an object that contains the schema 
Overrides: 

listSchema in class dkAbstractDatastore 

See Also: 

listEntities 

public Object listSchemaAttributes(String schemaEntry) 
throws DKException, Exception 

Lists the attributes that belong to a schema. Note: 
listSchemaAttributes( ) is deprecated. Replace by lis- 
tEntity Attributes. 

Parameters: 

schemaentry — the name of the schema. 
Returns: 

an object that contains the attributes that belong to this 

schema 
Overrides: 

listSchemaAttributes in class dkAbstractDatastore 

See Also: 

listEntityAttrs 

public dkcollection listEntities( ) throws DKException, 
Exception 

Gets a list of entities from persistent Datastore 
Returns: 

a collection of entity defs 
Throws: DKException 
if error occurs 
Overrides: 

listentities in class dkAbstractDatastore 
public String[ ] UstEntityNames( ) throws DKException, 



Exception 

Lists the available datastore sources that can be used to 

connect with. 
Returns: 

a collection of server definitions 
Overrides: 

listDataSources in class dkAbstractDatastore 
public String[ ] listDataSourceNames( ) throws 
DKException, Exception 

Lists the available datastore source names that can be 
used to connect with. 



Gets a list of entity names from persistent Datastore 
Returns: 

an array of entity names 
Throws: DKException 
if error occurs 
Overrides: 

listEntityNames in class dkAbstractDatastore 
public dkcollection listEntityAttrs(String entity Name) 
throws DKException, Exception 

Gets a list of attributes for a given entity name. 
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Parameters: 

entityName — name of entity to retrieve attributes for 
Returns: 

a dkCollection of dkAttrDef objects 
Throws: DKException 
if the entity name does not exist 
Overrides: 

listEntityAttrs in class dkAbstractDatastore 
public String[ ] listEntityAttrNames(String entityName) 
throws DKException, Exception 

Gets a list of attribute names for a given entity name. 

Parameters: 

entityName — name of entity to retrieve attribute names 

for 
Returns: 

an array of attribute names 
Throws: DKException 
if the entity name does not exist 
Overrides: 

listEntityAttrNames in class dkAbstractDatastore 
public void destroy( ) throws DKException, Exception 
datastore destroy — datastore cleanup if needed 
Overrides: 

destroy in class dkAbstractDatastore 
public void createDatabase(String database_name) throws 
DKException, Exception 

Create image search database 

Parameters: 

database _name — database name 
public void deleteDatabase(String database_name) throws 
DKException, Exception 

Deletes image search database 

Parameters: 

database__name — database name 
public void createCatalog(String database_name, String 40 
catalog_name) throws DKException, Exception 

Creates image search catalog 

Parameters: 

database_name — database name 
catalog__name — catalog name 
public void deleteCatalog(String database „name, 
String catalog__name) throws DKException, Exception 
Deletes image search catalog 
Parameters: 

database_name — database name 
catalog__name — catalog name 
public void openCatalog(String database_name, 
String catalog__name) throws DKException, Exception 
Opens QBIC catalog for a specified database 
Parameters: 

database_name — database name 

catalog_name — catalog name 
public void closecatalog( ) throws DKException, Exception 

Closes current catalog 
public void addColorFeature( ) throws DKException, 
Exception 

Adds color feature to the current catalog 
public void addDrawFeature( ) throws DKException, 
Exception 
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Adds draw feature to the current catalog 
public void addColorHistogramFeature( ) throws 
DKException, Exception 

Adds color histogram feature to the current catalog 
public void addTextureFeature( ) throws DKException, 
Exception 

Adds texture feature to the current catalog 
public void addFeature(intfeatureSelection, 

boolean bReCatalog) throws DKException, Exception 

Adds feature to the current catalog 

Parameters: 

featureSelection — specific feature 

bReCatalog — when true image search server reanalyze 
the new feature for existing images, 
public void remove ColorFeature( ) throws DKException, 
Exception 

Removes color feature from the current catalog 
public voidremoveDrawFeature( .)throwsDKException, 
Exception 

Removes draw feature from the current catalog 
public void removeColorHistogramFeature( ) throws 
DKException, Exception 

Removes color histogram feature from the current catalog 
public void removeTextureFeature( ) throws DKException, 
Exception 

Removes texture feature from the current catalog 
public voidprocessImages(DKImageRecordQBIC 
imageList[ ], 

int count) throws DKException, Exception 

Processes a list of images for the current catalog ^ 

Parameters: 

imageList — Image Record list 

count — number of objects in the array 
public synchronized void queuelmages 
(DKImageRecordQBIC imageList[ ], int count) throws 
DKException, Exception 

Puts a list of images into the image queue for later 
processing 

Parameters: 

imageList — Image Record list 

count — number of objects in the array 
public voidprocessImageQueue( ) throws DKException, 
Exception 

Processes the image queue, 
public void reCataloglmages(intfeatureSelectionList) 
throws DKException, Exception 

Recatalogs the images 

Parameters: 

features electionList — feature list, features are ored 
together. 

public Object listDatabases( ) throws DKException, Excep- 
tion 

Lists all databases in the image search server 
Returns: 

a collection of DKIndexQBIC objects 
public Object listCatalogs( ) throws DKException, Excep- 
tion 

Lists all catalogs in the current database 
Returns: 

a collection of DKIndexQBIC objects 
public Object listCatalogs(String database__name) throws 
DKException, Exception 
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Lists all catalogs in the specified database Parameters: 

Parameters: sourceMap — source name and mapping 

database_name — database name Returns: 

Returns: 5 the mapping name for the mapping information 

a collection of DKIndexQBIC objects Overrides: 
public Object kstFeatures( ) throws DKException, Excep- registerMapping in class dkAbstractDatastore 
tion public void unRegisterMapping(String mappingName) 

lists all features in the current catalog throws DKException, Exception 

Returns: 10 Unregisters mapping information for this Datastore 

a collection of DKIndexQBIC objects Parameters: 
public Object listColo.rImages( ) throws DKException, mappingName — name of the mapping information 
Exception Returns: 

Lists all images cataloged in the color feature in the 15 m 0 f register mapping objects' names 
current catalog. Overrides: 

Returns. unRegisterMapping in class dkAbstractDatastore 

a collection of DKImagelnfoQBIC objects public String[ ] UstMappingNames( ) throws DKException, 

public Object listHistogramImages( ) throws DKException, Exception 

Exception 20 Gets ^ ligt of (he register map pi n g S f or this Datastore 
Lists all images cataloged in the histogram feature in the Returns* 

current catalog. c . i . A , 

° an array or register mappmg objects names 

Returns: ~ 

Overrides: 

a collection of DKImagelnfoQBIC objects 25 i * ^ m • > T i « * t . ^ . . 

L1 . 4 iTA T ° , \ t^t^t- listMappingNames in class dkAbstractDatastore 

public Object listDrawImagest ) throws DKException. r « 5: , w . . /0t • 

t, . J e» v / r » public dkSchemaMapping getMapping(String 

^ mappingName) throws DKException, Exception 

lists all images cataloged in the draw feature in the Gets ta information for this Datastore 

current catalog. ^ 

3 n Parameters: 

Returns: 

_ —~ ~wr"w r r ™„ , . A mappingName — name of the mapping information 

a collection of DKImagelnfoQBIC objects 

public Object listTextureImages( ) throws DKException, Returns: 

Exception schema mapping object 

Lists all images cataloged in the texture feature in the 35 Overrides: 
current catalog. getMapping in class dkAbstractDatastore 

Returns* public synchronized dkExtension getExtension(String 

a collection of DKImagelnfoQBIC objects extensionName) throws DKException, Exception 

public String databaseName( ) throws DKException, Excep- Gets me extension object from a given extenstion name, 

tion 40 Parameters: 

Gets the current database name extensionName — name of the extension object. 

Returns: Returns: 

the database name extension object, 

public String catalogName( ) throws DKException, Excep- 45 Overrides: 

t 10n getExtension in class dkAbstractDatastore 

Gets the current catalog name public synchronized void addExtension(String 

Returns* extensionName, dkExtension extensionObj) throws 

the catalog name 50 D KE*«*ti°n, Exception 

public String g etLibServerName( ) throws DKException, Adds a new exlension ob J ect * 

Exception Parameters: 

Gets the library server name extensionname^name of new extension object 

Returns* extensionObj — the extension object to be set 

the library server name 55 0verrides: 

public dkDatastoreDef datastoreDef( ) throws addExtension in class dkAbstractDatastore 

DKException, Exception P ublic synchronized void removeExtension(String 

^ ' « „ . . extensionName) throws DKException, Exception 

Gets datastore definition „ . A . A 

Removes an existing extension object 

Returns: 60 Parameters: 

the meta-data (dkDatastoreDef) of this Datastore extensionName-name of extension object to be removed- 

0verrides: Overrides: 

datastoreDef in class dkAbstractDatastore removeExtension in class dkAbstractDatastore 

public String registerMapping(DKNVPair sourceMap) 6J pu b uc synchronized String[ ] listExtensionNames( ) throws 
throws DKException, Exception DKException, Exception 

Registers mapping information to this Datastore Gets the list of extension objects' names 
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Returns: 

an array of extension objects' names 
Overrides: 

listExtensionNames in class dkAbstracDatastore 5 
public DKDDO createDDO(String objectType, 
int Flags) throws DKException, Exception 
Creates a new DDO with object type, properties and 

attributes set for a given backend server. 
Parameters: 10 
objectType — the object type user wants to create 
Flags — to indicate various options to specific more detail 
characteristics of the DDO to create. For example, it may 

be a directive 
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to create a document DDO, a folder, etc. 
Returns: 

a new DDO of the given object type with all the properties 
and 

attributes set so that the user only need to set the attribute 

values 
Overrides: 

createDDO in class dkAbstractDatastore 
5. Text Search Datastore 

DKDatastoreTS is a specific version of dkDatastore and is 
used to query and access text search data. An example 
class definition for DKDatastoreTS is set forth below. 



DKDatastoreTS 

package com.ibm.mm.sdk.server.DKDatastoreTS 
public class DKDatastoreTS 

extends dkAbstractDatastore 

implements DKConstantDL, DKMessageldDL 

{ 

public DKDatastoreTS Q throws DKException, Exception 
public DKDatastoreTS (String configuration) throws DKException, Exception 
public void connect(String datastorc__name, 
public void connect(Struig server_name, 
String port, 

char communication__type) throws DKException, Exception 
public void disconnect Q throws DKException, Exception 
public Object getOption(int option) throws DKException, Exception 
public void setOption(int option, 

Object value) throws DKException, Exception 
public Object evaluate(String command, 

short commandLangType, 

DKNVPair params[]) throws DKException, Exception 
public Object evaluate(dkQuery query) throws DKException, Exception 
public Object evaluate(DKCQExpr qe) throws DKException, Exception 
public dkResultSetCursor execute(String command, 
short commandLangType, 

' DKNVPair params[]) throws DKException, Exception 
public dkResullSetCursor execute(dkQuery query) throws DKException, Exception 
public dkResultSetCursor executefDKCQExpr cqe) throws DKException, Exception 
public void executeWithCallback(dkQuery query, 

dkCallback caUbackObj) throws DKException, Exception 
public void executeWithCallback(Stiing command, 

short commandLangType, 

DKNVPair params[L 

dkCallback caUbackObj) throws DKException, Exception 
public void executeWithCalIback(DKCQExpr qe, 

dkCallback caUbackObj) throws DKException, Exception 
public dkQuery createQuery(String command, 
short commandLangType, 

DKNVPair paramsf]) throws DKException, Exception 
public dkQuery create Que ry(DKCQExpr qe) throws DKException, Exception ' 
public void addObject(dkDataObject ddo) throws DKException, Exception 
public void deleteObjectfdkDataObject ddo) throws DKException, Exception 
public void retrieveObject(dkDataObject ddo) throws DKException, Exception 
public void updateObjcct(dkDataObject ddo) throws DKException, Exception 
public void commit() throws DKException, Exception 
public void rotlbackO throws DKException, Exception 
public boolean isConnectedO throws Exception 
public String datastoreName() throws Exception 
public String datastoreTypcQ throws Exception 
public DKHandle connection0 throws Exception 
public DKHandle handle(String type) throws Exception 
public String userNameO throws Exception 

public dkCollection listDataSourcesQ throws DKException, Exception 
public Stiing[] listDataSourceNamesO throws DKException, Exception 
public Object listServersQ throws DKException, Exception 
public Object listSchemaQ throws DKException, Exception 

public Object listSchemaAttributes(String schemaEntry) throws DKException, Exception 

public dkCollection listEntities0 throws DKException, Exception 

public String[] listEntityNamesO throws DKException, Exception 

public dkCollection listEntityAttrs (String entityNatne) throws DKException, Exception 

public String[] listEntityAttrNamesfString entityName) throws DKException, Exception 

public void startup dateIndex(String indexName) throws DKException, Exception 
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public void clearIndex(String indexName) throws DKException, Exception 
public void createIndex(DK[ndeiInfoTS newlndex) throws DKExccption, Exception 
public void deleteIndex(String indexName) throws DKException, Exception 
public DKIndexInfoTS gctindexInformation(String indexName) throws DKException,, 
Exception 

public DKIndexFuncStatusTS getIndexFunctionStatus(String indexName) throws 

DKException, Exception 
public void setlndexFunctionStatusfStiing indexName, 

int actionld) throws DKException, Exception 
public dkDatastoieDef datastoreDefO throws DKException, Exception 
public DKMatchesInfoTS getMatches(dkResultSetCujsor cursor, 

String documentld, 

String textlndexName, 

boolean uscDictiooary) throws DKException, Exception 
public String rcgisterMapping(DKNVPair sourceMap) throws DKException, Exception 
public void unRegisterMapping(String mappingName) throws DKException, Exception 
public String!] listMappingNamesO throws DKException, Exception 
public dkSchemaMapping getMapping(String mappingName) throws DKException, 
Exception 

public synchronized dkExtension getExtensioa(String extensionName) throws 

DKException, Exception 
public synchronized void addExtension(String extensionName, 

dkExtension extensionObj) throws DKException, Exception 
public synchronized void removeExtension(String extensionName) throws DKException, 

Exception 

public synchronized String^] listExtensionNamesO throws DKException, Exception 
public DKDDO createDDO (String objecOype, 

int Flags) throws DKException, Exception 
public void destroy 0 throws DKException, Exception 

> 
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The following methods are part of the DKDatastoreTS 30 
class: 

public DKDatastoreTS( ) throws DKException, Exception 
Constructs the datastore and initializes the datastore. 

public DKDatastoreTS(String configuration) throws 

DKException, Exception 35 
Constructs the datastore and initializes the datastore. 

public void connect(String datastore name, 

String user_name, 

String authentication, 40 
String connect_string) throws DKException, Exception 
Connects to a datastore. 
Parameters: 

datastore_name — the datastore name used for connection 45 
user_name — the user name used for connection 
authentication — the authentication used for connection 
connect_string — the connect string used for connection. 

This is used to 
provide additional connection options. 
Overrides: 

connect in class dkAbstractDatastore 
public void connect(String server_name, 

String port, 55 
char communication__type) throws DKException, Excep- 
tion 

Connects to a datastore. 
Parameters: 

server _name — the hostname where the text server is 
located 

port — the port where the text server is located 
communication_type — the communication type T for 
TCPIP or P for PIPES 65 
public void disconnect ) throws DKException, Exception 
Disconnects to a datastore. 



Overrides: 

disconnect in class dkAbstractDatastore 
public Object getOption(int option) throws DKException, 
Exception 

Gets a datastore option. 

Parameters: 

option — the option identifier 

Returns: 

an option value 

Overrides: 

getOption in class dkAbstractDatastore 
public void setOption(int option, 

Object value) throws DKException, Exception 

Sets a datastore option. 

Parameters: 

option — the option identifier 
value — the option value 
Overrides: 

setOption in class dkAbstractDatastore 
public Object evaluate(String command, 
short commandLangiype, 

DKNVPair params[ ]) throws DKException, Exception 

Evaluates the query. 

Parameters: 

command — a query string 

commandLang — a query type 

params — additional query option in name/value pair 

Returns: 

a collection of the results 
Overrides: 

evaluate in class dkAbstractDatastore 
public Object evaluate (dkQuery query) throws DKExcep- 
tion Exception 
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Evaluates the query. 

Parameters: 

query — a query object 

Returns: 

a collection of the results 
Overrides: 

evaluate in class dkAbstractDatastore 
public Object evaluate(DKCQExpr qe) throws 
DKException, Exception 

Evaluates the query. 

Parameters: 

qe — a common query expression object 
Returns: 

a collection of the results 
Overrides: 

evaluate in class dkAbstractDatastore 
public dkResultSetCursor execute(String command, 
short commandLangType, 

DKNVPair params[ ]) throws DKException, Exception 

Executes the query. 

Parameters: 

command — a query string 

commmdLang — a query type 

params — additional query option in name/value pair 

Returns: 

resultSetCursor which represents a datastore cursor. 
Overrides: 

execute in class dkAbstracDatastore 
public dkResultSetCursor execute(dkQuery query) throws 
DKException, Exception 

Executes the query. 

Parameters: 

query — a query object 

Returns: 

resultSetCursor which represents a datastore cursor. 
Overrides: 

execute in class dkAbstractDatastore 
public dkResultSetCursor execute(DKCQExpr cqe) throws 
DKException, Exception 

Executes the query. 

Parameters: 

qe — a common query expression object 
Returns: 

resultSetCursor which represents a datastore cursor. 
Overrides: 

execute in class dkAbstractDatastore 
public void executeWithCallback(dkQuery query, 

dkCallback callbackObj) throws DKException, Excep- 
tion 

Executes the query with callback function. 

Parameters: 

qo — a query object 

callbackObj — a dkCallback object 

Overrides: 

execute WithCallback in class dkAbstractDatastore 
public void executeWithCallback(String command, 
short commandLangType, 
DKVPairparams[ ], 
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dkCallback callbackObj) throws DKException, Excep- 
tion 

Executes the query with callback function. 
Parameters: 

command — a query string 
commandLang — a query type 

params — additional query option in name/value pair 
callbackObj — a dkCallback object 
10 Overrides: 

executeWithCallback in class dkAbstractDatastore 
public void executeWithCallback(DKCQExpr qe, 

dkCallback callbackObj) throws DKException, Excep- 

15 tion 

Executes the query with callback function. 
Parameters: 

qe — a common query expression object 
callbackObj — a dkCallback object 
Overrides: 

executeWithCallback in class dkAbstractDatastore 
public ckQuery createQuery(String command, 
short commandLangType, 
25 DKNVPair paramsf ]) throws DKException, Exception 
Creates a query object. 
Parameters: 

command — a query string 
30 commandLang — a query type 

params — additional query option in name/value pair 
Returns: 
a query object 
35 Overrides: 

createQuery in class dkAbstractDatastore 
public dkQuery create Query(DKCQExpr qe) throws 
DKException, Exception 
Creates a query object. 
Parameters: 
qe — a common query expression object 
Overrides: 

createQuery in class dkAbstractDatastore 
45 public void addObject(dkDataObject ddo) throws 
DKException, Exception 
Adds this ddo to this datastore. 
Parameters: 

ddo — the ddo to be added to this Datastore 
Overrides: 

addObject in class dkAbstractDatastore 
public void deleteObject(dkDataObject ddo) throws 
DKException, Exception 
Deletes this ddo from this datastore. 
Parameters: 

ddc— the ddo to be deleted from this Datastore 
Overrides: 

deleteObject in class dkAbstractDatastore 
60 public void retrieveObject(dkDataObject ddo) throws 
DKException, Exception 
Retrieves this ddo from this datastore. 
Parameters: 

65 ddo — the ddo to be retrieved from this Datastore 
Overrides: 

retrieve Object in class dkAbstractDatastore 
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public void updateObject(dkDataObject ddo) throws 
DKException, Exception 

Updates this ddo in this datastore. 

Parameters: 

ddo — the ddo to be updated in this Datastore 
Overrides: 

updateObject in class dkAbstractDatastore 
public void commit( ) throws DKException, Exception 
Commits a datastore transaction 10 
Overrides: 

commit in class dkAbstractDatastore 
public void rollback( ) throws DKException, Exception 
Rolls back a datastore transaction 15 
Overrides: 

rollback in class dkAbstractDatastore 
public boolean isconnected( ) throws Exception 

Checks to see if the datastore is connected. 

„ 20 

Returns: 

rue if connected 

Overrides: 

isConDected in class dkAbstractDatastore 
public String datastoreNarne( ) throws Exception 25 
Gets the name of this datastore object. Usually it repre- 
sents a datastore source's server name. 
Returns: 

datastore name 30 
Overrrides: 

datastoreName in class dkAbstractDatastore 
public String datastoreiype( ) throws Exception 
Gets the datastore type for this datastore object 
Returns: 
datastore type 
Overrides: 

datastoreType in class dkAbstractDatastore 
public DKHandle connection( ) throws Exception 40 
Gets the connection handle for a Datastore 
Returns: 

connection handle 

Overrides: 45 
connection in class dkAbstractDatastore 
public DKHandle handle(String type) throws Exception 
Gets a datastore handle 

Parameters: 5Q 

type — type of datastore handle wanted 

Returns: 

a datastore handle 
Overrides: 

55 

handle in class dkAbstractDatastore 
public String userName( ) throws Exception 

Gets the user name for this datastore object 
Returns: 

user name 60 
Overrides: 

userName in class dkAbstractDatastore 
public dkcollection listDataSources( ) throws DKException, 
Exception 65 

Lists the available datastore sources that can be used to 
connect with. 
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Returns: 

a collection of server definitions 
Overrides: 

listDataSources in class dkAbstractDatastore 
public String[ ] HstDataSourceNames( ) throws 
DKException, Exception 

Lists the available datastore source names that can be 
used to connect with. 

Returns: 

an array of server names 
Overrides: 

listDataSourceNames in class dkAbstractDatastore 
public Object listservers( ) throws DKException, Exception 
List the available datastore sources that can be used to 

connect with. Note: listServers( ) is deprecated. 

Replace by listDatasources. 
Returns: 

a collection of server definitions 
Overrides: 

listServers in class dkAbstractDatastore 
See Also: 
listDataSources 
public Object listschema( ) throws DKException, Exception 
Lists the entities that belong to this datastore. Note: 

listSchema( ) is deprecated. Replace by listEntities. 
Returns: 

an object that contains the schema 
Overrides: 

listSchema in class dkAbstractDatastore 

See Also: 

listEntities 

public Object listSchemaAttributes(String schemaEntry) 
throws DKException, Exception 
Lists the attributes that belong to a schema. Note: 
listSchemaAttributes( ) is deprecated. Replace by lis- 
tEntity Attributes. 
Parameters: 

schemaentry — the name of the schema. 
Returns: 

an object that contains the attributes that belong to this 

schema 
Overrides: 

listSchemaAttributes in class dkAbstractDatastore 

See Also: 

listEntityAttrs 

public dkCollection listEntities( ) throws DKException, 
Exception 

Gets a list of entities from persistent Datastore 
Returns: 

a collection of entity defs 
Throws: DKException 
if error occurs 
Overrides: 

listEntities in class dkAbstractDatastore 
public String[ ] listEntityNames( ) throws DKException, 
Exception 

Gets a list of entity names from persistent Datastore 
Returns: 

an array of entity names 



11/28/2003, EAST Version: 1.4.1 



US 6,370,541 Bl 



65 



66 



Throws: DKException 
if error occurs 
Overrides: 

listEntityNames in class dkAbstractDatastore 
public dkCollection listEntityAttrs(String entityName) 
throws DKException, Exception 

Gets a list of attributes for a given entity name. 

Parameters: 

entityName — name of entity to retrieve attributes for 
Returns: 

a dkCollection of dkAttrDef objects 

Throws: DKException 

if the entity name does not exist 

Overrides: 

listEntityAttrs in class dkAbstractDatastore 
public Stringf ] listEntityAttrNames(String entityName) 
throws DKException, Exception 

Gets a list of attribute names for a given entity name. 

Parameters: 

entityName — name of entity to retrieve attribute names 

for 
Returns: 

an array of attribute names 

Throws: DKException 

if the entity name does not exist 

Overrides: 

listEntityAttrNames in class dkAbstractDatastore 
public void startTJpdateIndex(String indexName) throws 
DKException, Exception 

Starts the indexing process. 

Parameters: 

indexName — the name of the search index, 
public void clearIndex(String indexName) throws 
DKException, Exception 

Clears all indexed terms from a search index. 

Parameters: 

indexName — the name of the search index, 
public void createIndex(DKIndexInfoTS newlndex) throws 
DKException, Exception 

Creates a search index. 

Parameters: 

newlndex — the search index to be created, 
public void deleteIndex(String indexName) throws 
DKException, Exception 

Deletes a search index. 

Parameters: 

indexName — the name of a search index, 
public DKIndexInfoTS getIndexInformation(String 
indexName) throws DKException, Exception 

Gets index information about a search index. 

Parameters: 

indexName — the name of a search index. 
Returns: 

a search index object which contains search index infor- 
mation. 

public DKIndexFuncStatusTS getlndexFunctionStatus 
(String indexName ) throws DKException, Exception 

Gets indexing function status, document and document 
message queue count for search index. 
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Parameters: 

indexName — the name of a search index. 
Returns: 

a search index function status object which contains the 

indexing 
function status, 
public void setIndexFunctionStatus(String indexName, 
int actionid) throws DKException, Exception 
Set indexing function status for a search index. 
Parameters: 

indexName — the name of a search index. 

actio nald — the indicator applied to a text search function. 
It can be 

enabled, disabled or reset, 
public dkDatastoreDef datastoreDef( ) throws 
DKException, Exception 

Get datastore definition 

Returns: 

the meta-data (dkDatastoreDef) of this datastore 
Overrides: 

datastoreDef in class dkAbstractDatastore 
public DKMatchesInfoTS getMatches(dkResultSetCursor 
cursor, 

String documentld, 
String textlndexName, 

boolean useDictionary) throws DKException, Exception 
Get Match Information given indexName and document 
id 

Returns: 

A DKMatchesInfoTS object that contains match informa- 
tion public String registerMapping(DKNVpair 
sourceMap) throws DKException, Exception 

Registers a mapping definition to this datastore. Mapping 
is done by Entities. 

Parameters: 

sourceMap — source name and mapping, a DKNVPair 
class with the following possible values: 

("BUFFER",): buffer_ref is a reference to a string in 
memory 

("FILE",): file_name is the name of the file containing 

the mapping 
("URL",): URL- address location of the mapping 
("LDAP",): LDAP file-name 

("SCHEMA",): a reference to a dkSchemaMapping 
object defining the mapping. Currently, only 
"SCHEMA" option is supported, others may be added 
later. 

Returns: 

the name of the mapping definition. 
Overrides: 

registerMapping in class dkAbstractDatastore 
See Also: 

unRegisterMapping 
public void unRegisterMapping(String mappingName) 
throws DKException, Exception 

Unregisters mapping information for this Datastore 

Parameters: 

mappingName — name of the mapping information 
Returns: 

an array of register mapping objects' names 



11/28/2003, EAST Version: 1.4.1 



US 6,370,541 Bl 



67 



68 



Overrides: 

unRegisterMapping in class dkAbstractDatastore 
public String[ ] listMappingNames( ) throws DKException, 
Exception 

Gets the list of the register mappings for this Datastore 
Returns: 

an array of register mapping objects' names 
Overrides: 

listMappingNames in class dkAbstractDatastore 
public dkSchemaMapping getMapping(String 
mappingName) throws DKException, Exception 

Gets mapping information for this Datastore 

Parameters: 

mappingName — name of the mapping information 
Returns: 

the schema mapping object 
Overrides: 

getMapping in class dkAbstractDatastore 

See Also: 

registerMapping 
public synchronized dkExtension getExtension(String 
extensionName) throws DKException, 

Exception 

Gets the extension object from a given extension name. 
Parameters: 

extensionName — name of the extension object. 
Returns: 

extension object. 
Overrides: 

getextension in class dkAbstractDatastore 
public synchronized void addExtension(String 
extensionName, 

dkExtension extensionObj) throws DKException, Excep- 
tion 

Adds a new extension object. 
Parameters: 

extensionName — name of new extension object 
extensionObj — the extension object to be set 
Overrides: 
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addExtension in class dkAbstractDatastore 
public synchronized void removeExtension(String 
extensionName) throws DKException, Exception 

Removes an existing extension object 

Parameters: 

extensionName — name of extension object to be removed 
Overrides: 

removeExtension in class dkAbstractDatastore 
public synchronized String[ ] listExtensionNames( ) throws 
DKException, Exception 

Gets the list of extension objects' names 

Returns: 

an array of extension objects' names 
Overrides: 

listExtensionNames in class dkAbstractDatastore 
public DKDDO createDDO(String objectType, 
int Flags) throws DKException, Exception 
Creates a new DDO with object type, properties and 

attributes set for a given backend server. 
Parameters: 

objectType — the object type user wants to create 
Flags — to indicate various options to specify more detail 
characteristics of the DDO to create. For example, it may 

be a directive 
to create a document DDO, a folder, etc. 
Returns: 

a new DDO of the given object type with all the properties 
and 

attributes set, so that the user only need to set the attribute 

values 
Overrides: 

createDDO in class dkAbstractDatastore 
public void destroy( ) throws DKException, Exception 
datastore destroy — datastore cleanup if needed 
Overrides: 

destroy in class dkAbstractDatastore 
6. Dynamic Data Objects 
DKDDOBase is the base class to represent a Dynamic 

Data Object (DDO). An example class definition for 

DKDDOBase is set forth below. 



DKDDOBase 

package com.ibm.mmm.sdk.common.DKDDOBase 
public class DKDDOBase 
extends dkDataObject 

implements DKConstant, DKMessageld, Serializable 

{ 

public DKDDOBasef ) 
public DKDDOBas e(short initialSize) 
public DKDDOBas e(DKDDOBase ddo) 
public DKDDOBase(String objectType) 
public DKDDOBas e(String objectType, 

short initialSize) 
public DKDDOBase(DKPid pid) 
public DKDDOBase(DKPid pid, 

short initialSize) 
public short protocolf ) 
public String getObjectType( ) 
public void set ObjectType (String toObjectType) 
public boolean updatable( ) 
public short addData( ) throws DKUsageError 
public short addData(String data_name) throws DKUsageError 
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public short addDataProperty (short data_id) throws DKUsagcError 
public short addDataProperty (short data_id, 

String property__name) throws DKUsageError 
public short addDataProperty (short data_id, 

String property^ Bame, 

Object property_value) throws DKUsagcError 
public short data Count ( ) 

public short dataPropertyCount(short data_id) throws DKUsageError 
public void setDataPropeity(short data_id, 
short prcperty_id, 

Object property_value) throws DKUsageError 
public Object getDataProperty(short data_id, 

short property_id) throws DKUsageError 
public void setDataPropertyName(short data id, 

short property_id, 

String property__name) throws DKUsage Error 
public String getDataPropertyNarne(short data_id, 

short property_id) throws DKUsageEnor 
public void setData(short data^id, 

Object data value) throws DKUsageError 

public Object getDatafsort data_id) throws DKUsageError 
public void setDataName(short data_id, 

String data_name) throws DKUsageError 
public String getDataName(short data_id) throws DKUsageError 
public short dataId(String data_jiame) throws DKUsageError 
public short dataPropertyId(short data_id, 

String data„property_name) throws DKUsageError 
public Object getDataByName(String data_name) throws DKUsageError 
public Object getDataPropcrtyByNarne(short data_id, 

String data_property_name) throws DKUsageError 
public Object getDataPropertyByName(String data^name, 

String data_property_name) throws DKUsageError 
public void setNull(short data_id) throws DKUsageError 
public boolean isNull(short data_id) throws DKUsageError 
public boolean isDataSet(short data_id) throws DKUsageError 

public boolean isDataPropertySet(short data id, 

short property_jd) throws DKUsageEnor 
public short addProperty( ) throws DKUsageError 
public short addProperty(String property_name) throws DKUsageError 
public short addProperty(String property__name, 

Object property _value) throws DKUsageError 
public short propertyCount( ) throws DKUsagcError 
public void setProperty (short property_jd, 

Object property_value) throws DKUsageError 
public Object gctProperty (short propcrty_id) throws DKUsagcError 
public void setPropertyName(short property_Jd, 

String propcrty_name) throws DKUsageError 
public String getPropertyName(short property_id) throws DKUsageError 
pubic short propertyId(String property _name) throws DKUsageError 
public Object gctProperty By Name (String propcrty__name) throws DKUsageError 
public boolean isPropertySet(short property_jd) throws DKUsageError 



The following methods are part of the DKDDOBase 
class: 

public DKDDOBase( ) 

Constructs a DDO Base object, 
public DKDDOBase(short initialSize) 

Constructs a DDO Base object which has enough space 

for the given initial number of data-items. 
Parameters: 

initialSize — initial number of data items, 
public DKDDOBase (DKDDOBase ddo) 

Constructs a DDO Base object from an existing DDO 

Base (copy contmctor). 
Parameters: 

ddo — a DDO Base object, 
public DKDDOBase(String objectType) 

Constructs a DDO Base object for a given object type. 
Parameters: 

objectType — the object type. 



public DKDDOBase(String objectType, 
short initialSize) 

Constructs a DDO Base object for a given object type, 

with an initial number of data-items. 
Parameters: 

objectType — the object type. 

initialSize — initial number of data items, 
public DKDDOBase(DKPid pid) 

Constructs a DDO Base object with a given Pid. 

Parameters: 

pid — the Pid object 
public DKDDOBase (DKPid pid, 

short initialSize) 

Constructs a DDO Base object with a given Pid and an 

initial number of data-items. 
Parameters: 
pid — the Pid object. 

initialSize — initial number of data items, 
public shortprotocol( ) 
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Returns the protocol type supported by this data-object. In Parameters: 

this case, it is DK_DDO, which essentially means that data id t ne data-id. 

this data-object can be made persistent with the help of „„™ a 

. J . t , . r „ ^ Tjr r . property name — property name. 

an associated datastore object. The DK^_DDO protocol 

consists of get/setData, get/setDataProperty, and other 5 prop erty_value— property value, 

methods in this object, which support the representa- Returns: 

tion of a self describing data-object. data property number (property- id). 

Returns: public short datacount( ) 

the protocol. Gets the number of data-items in this data-object. 

Overrides: 10 Returns: 

protocol in class dkDataobject number of data-items, 

public String getObjectType( ) public short dataPropertyCount(short data_id) throws 

Gets the type of this data-object. DKUsageError 

Returns: 15 Gets the number of properties associated with this data- 

the object type. item * 

Overrides: Parameters: 

getObjectType in class dkDataobject / data^id — the data-id. 

public void setObjectType(String toObjectType) Returns: 

Sets the type of this data-object and synchronizes it with 20 the number of properties. 

the object type of its Pid. public void setDataProperty(short data_id, 

Parameters: short property__id, 

toObjectType— the object type. object property_value) throws DKUsageError 

public boolean updatable( ) ^ ^ {h& ^ Qf a ^ property m a data _ item 

Returns true if this data object is updatable. „ 

R tur Parameters: 

.,■ * t , data_id — data -id. 
true if updatable. 

public short addData( ) throws DKUsageError property_id— property-id. 

Adds a new data-item to this databject and returns the new 30 Property__value-the property value. 

data-item number (data-d). P ubhc 0b J ect getDataProperty(short data„id, 

Returns: snort property_id) throws DKUsageError 

the data-item number (data-id). Gets ^ valuc of a & ycn property in a data-item. 

public short addData(String data_name) throws DKUsag- 35 Parameters: 

eE rror data_id— data-id. 

Adds a new data-item wit the given name to this data- property_id property-id. 

object and returns the new data-item number (data -id). Returns- 
Parameters: 



data_name^data-item name. 40 plibhc void setDataPropertyNametshort data__id, 



property value, 
ublic void setDat 
short property_id, 



Returns: 

data-item number (data-id). String property name) throws DKUsa eError 

public short addDataProperty(short data_id ) throws „ . S , / 

DKUsageError ^ ets lne name or - a & vcn property m a data-item. 

Adds a new property to a given data-item and returns the 45 Parameters: 

new property number property-id). data_id — data-id. 
Parameters: property_jd — property -id. 
data_id — data-id . propertyk_name — property name. 
Returns: 50 public String getDataPropertyName(short data_id), 
data-property number (property-id). short property_Jd) throw DKUsageError 
public short addDataProperty(short data_id, G ets the name of a given data-item. 
String property_name) throws DKusageError Parameters- 
Adds a new property with the given name to the data-item ^ ^ data-id 

and returns the new property number (property-id). 55 — 
Parameters: property_id-property-id. 

data_id^iata id. Returns: 

property_name — property name. property name. 

Returns' public void setData(short data_id, 

data property number (property-id). 6 ° 0b J cct data_value) throws DKUsageError 
public short addDataProperty(short data_id, Sets the value of a -given data-item. 

String property_jiame, Parameters: 

Object property_value) throws DKUsageError data_value— data-id. 

Adds a new property with the given name and value to the 65 data_value — data value. 

data-item and returns the new property number public Object getData(short data_Jd) throws DKUsageError 
(property-id). Gets the value of a given data-item. 
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Parameters: 

data_id — data-id. 

Returns: 

data value, 
public void setDataName(short data_id, 

String data_ name) throw DKUsageError 

Sets the name of a given data-item. 

Parameters: 

da ta__id — d ata -id . 

data_name — data name, 
public String gatDataName(short data_id) throws DKUsa- 
geError 

Gets the name of a given data-item. 

Parameters: 15 

data_id — data-item. 

Returns: 

data name. 

public short dataId(String data__name) throws DKUsageEr- 20 
ror 

Gets the data-id of a given data-item name. 
Parameters: 

data_jiame — data name. 
Returns: 
the data-id. 
public short dataPropertyId(short data^id, 

String data_property_name) throws DKUsageError 

Gets the property-id of a given property-name in a data- 30 

item. 
Parameters: 
data_id — data-id. 

data__property_name — data-property name. 

Returns: 

the property-id. 
public Object getDataByName(String data_ name) throws 
DKUsageError 

Gets the value of a data-item given its name. 

Parameters: 

data__name — data -item name. 
Returns: 
data value. 

public Object getDataPropertyByName(short data_jd, 
String data__property_name) throws DKUsageError 
Gets the value of a given property-name of a data-item id. 
Parameters: 
data_id — data-id. 

data_property_name — data-property name. 
Returns: 
property value, 
public Object getDataPropertyByName(String data_name, 
String data_property_name) throws DKUsageError 
Gets the value of a given property-name of a data-item 

name. 
Parameters: 

data__name — data-item name. 
data_property__name — data-property name. 
Returns: 
property value, 
public void setNull(short data_Jd) throws DKUsageError 
Sets the value of a data-item to a null value. The data- item 

must be nullable, and the data-object must be updat- 

able. 
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Parameters: 
data _id — data-id. 
public boolean isNull(short data_id) throws DKUsageError 
Returns true if the value of this data-item is null. 
Returns: 

true if data-item value is null, 
public boolean isDataSet(short data _Jd) throws DKUsag- 
eError 

Returns true if this data-item has been set to a value. 
Returns: 

true if data item value is set. 
public boolean isDataPropertySet(short data_id, 
short property_id) throws DKUsageError 
Returns true if a given properly of a data-item is set. 
Returns: 

true if data item property value is set. 
public short addProperty( ) throws DKUsageError 

Adds a new property to this DDO and returns the new 

property number (property-id). 
Returns: 

the new property number (property id), 
public short addProperty(String property__name) throws 
DKUsageError 

Adds a new property with a given name to this DDO and 
returns the new property number (property-id). 

Parameters: 

property_name — property name. 
Returns: 

property number (property -id), 
public short addProperty(String property_name, 
Object property_value) throws DKUsageError 
Adds a new property with a given name and value to this 
DDO. and returns the new property number (property- 

id). 

Parameters: 

property_jiame — property-name. 
property_value — property value. 
Returns: 

the property number (property-id), 
public short propertycount( ) throws DKUsageError 
Gets the number of properties associated with this DDO. 
Returns: 

the number of properties, 
public void setProperty(short property__id, 
Object property_value) throws DKUsageError 
Sets the value of a given property in this DDO. 
Parameters: 

property_id — property-id. 

property_value — property value. 

public Object getProperty (short proper ty id) throws 

DKUsageError 

Gets the value of a given property in this DDO. 

Parameters: 

property_id — property-id. 
Returns: 
property value, 
public void setPropertyName(short property _jd, 
String propertyjame) throws DKUsageError 
Sets the name of a given property in this DDO. 
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Parameters: 

property_id — property-id. 

property_name — property name, 
public String getPropertyName(short property_id) throws 
DKUsageError 

Gets the name of a given property in this DDO. 

Parameters: 

property__id — property-id. 
Returns: 

the property name, 
public shortpropertyId(String property_name) throws 
DKUsageError 

Gets the property-id of a given property-name in this 
DDO. 

Parameters: 

property__name — property-name. 

Returns: 

the property-id. 
public Object getPropertyByName(String property_name) 
throws DKUsageError 

Gets the value of a given property-name in this DDO. 
Parameters: 

property_name — property-name. 
Returns: 

the property value, 
public boolean isPropertySet(shortproperty_id) throws 
DKUsageError 

Returns true if the given property in this DDO has been 

set to a value. 
Parameters: 

property_id — property -id. 
Returns: 

true if the property is set 

DKDDO is the class to represents a Dynamic Data Object. 
It is a sub -class of DKDDOBase with additional meth- 
ods to support persistency, such as add( ), retrieve( ), 
update( ), and del( ). An example class definition for 
DKDDO is set forth below. 
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DKDDO 



package com. ibm.mm.sdk. common. DKDDO 
public class DKDDO 

extends DKDDOBase 

implements DKConstant, Serializable 

{ 

public DKDDO ( ) 

public DKDDO (short initialize) 

data-items. 

public DKDDOfDKDDO ddo) 
public DKDDO(String objecrfype) 
public DKDDO(String objecOype, 
public DKDDO(dkDatastore ds, 

String objectType) 
public DKDDO(dkDatastore ds, 

String objectiype, 

short initial Size) 
public DKDDO(DKPid pid) 
public DKDDO(DKPid pid, 

short initial Size) 
public DKDDO(dfcDatastore ds, 

DKPid pid) 
public DKDDO (dkDatasto re ds, 

DKPid pid, 
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-continued 
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short initialSizc) 
public void setDatastore(dkDatastore ds) 
public dkDatastore getDatastore(~) 
public short protocolf ) 

public void add( ) throws DKException, Exception 
public void rctrievef ) throws DKException, Exception 
public void update( ) throws DKException, Exception 
public void del( ) throws DKException, Exception 
} 



The following methods are part of the DKDDO class: 
public DKDDOO( ) 

Constructs a DDO object, 
public DKDDO(short initialSize) 

Constructs a DDO object which has enough space for the 
given initial number of data-items. 

Parameters: 

initialSize — the initial number of data-items, 
public DKDDO(DKDDO ddo) 

Constructs a DDO object by copying another DDO object 

(copy constructor). 
Parameters: 

ddo — the other existing DDO object, 
public DKDDO(String objectType) 

Constructs a DDO object for a given object type. 
Parameters: 

objectType — an object-type, 
public DKDDO(String objectType, 
short initialSize) 

Constructs a DDO object for a given object type, with an 

initial number of data-items. 
Parameters: 

objectType — an object-type. 

initialSize — the initial number of data items, 
public DKDDO(dkDatastore ds, 

String objectiype) 

Constructs a DDO object 

Parameters: 

ds — a datastore object. 

objectType — an object-type, 
public DKDDO(dkDatastore ds, 

String objectiype, 

short initialSize) 

Constructs a DDO object for a given object type, with an 
initial number of data-items and the datastore associ- 
ated with it. 

Parameters: 

ds — a datastore object. 

objectType — an object-type. 

initialSize — the initial number of data-items, 
public DKDDO(DKPid pid) 

Constructs a DDO object with a given Pid. 

Parameters: 

pid— a Pid object, 
public DKDDO(DKPid pid, 

short initialSize) 

Constructs a DDO object with a given Pid and an initial 

number of data-items. 
Parameters: 
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pid — a Pid object. 

initialSize — the initial number of data-items, 
public DKDDO(dkDatastore ds, 
DKHd pid) 

Constructs a DDO object with a given Pid and the 

datastore associated with it. 
Parameters: 

ds — a datastore object, 
pid — a Pid object, 
public DKDDO(dkDatastore ds, 
DKPid pid, 
short initialSize) 

Constructs a DDO object with a given Pid, the datastore 
associated with it, and an initial number of data-items. 
Parameters: 
ds — a datastore object, 
pid — a Pid object. 

initialSize — the initial number of data-items, 
public void setDatastore(dkDatastore ds) 

Sets this datastore as the one associated with this DDO; 
that is, the datastore to keep the persistent copy of this 
DDO. 

Parameters: 

ds — a datastore object, 
public datastore getDatastore( ) 

Gets the associated datastore for this DDO. 

Returns: 

the datastore object, 
public shortprotocol( ) 

Returns the protocol type supported by this data-object. In 
this case, it is DK_PDDO, which essentially means 
that this object knows the datastore which it is associ- 
ated with. With the help of the datastore, this object can 
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transfer itself in and out of the datastore, thus making 

itself persistent. 
Returns: 
the protocol 
Overrides: 

protocol in class DKDDOBase 
public void add( ) throws DKException, Exception 

Adds this data-object to the persistent store. An initial 
entry of persistent copy of this data-object is created, 
according to the corresponding entity structure defined 
in the datastore. Onlypersistent data-items (or 
attributes) are saved, 
public void retrieve( ) throws DKException, Exception 

Retrieve this data-object from the persistent store. The 
in -memory values of this data -object is replaced with 
the persistent copy retrieved from the datastore. Only 
persistent data-items (or attributes) are retrieved, 
public void update( ) throws DKException, Exception 

Updates this object in the persistent store. The persistent 
copy of this data-object is updated with the current 
values in-memory. Only persistent data -items (or 
attributes) are updated, 
public void del( ) throws DKException, Exception 

Deletes this object from the persistent store. The persis- 
tent copy of this data-object is deleted from the datas- 
tore. The in-memory copy of this object is not affected. 
After this method is executed, a subsequent call to 
retrieve( ), update( ), or del( ), will cause an exception 
because the persistent copy of this data-object no 
longer exists. 
7. Extended Data Objects 

The dkXDO class is a common abstract class that can 
represent a complex LTDT(User Defined Type) or 
LOB(Large Object).- An example class definition for 
dkXDO is set forth below. 



dkXDO 



package com.ibm.mm.sdk.common.dlcXDO 
public abstract class dkXDO 

extend dkXDOBase 

implements DKConstant, Serializable 

public abstract void setPid(DKPidXDO aPidXDO) throws DKUsagcError 
public abstract DKPidXDO getPid( ) 
public abstract DKPidXDO getPidObject( ) 

public abstract void setPidObject(DKPidXDO aPidXDO) throws DKException 

public abstract void add( ) throws DKException, Exception 

public abstract void retrieve( ) throws DKException, Exception 

public abstract void update( ) throws DKException, Exception 

public abstract void del( ) throws DKException, Exception 

public abstract boolean isContentChanged( ) 

public abstract boolean isSet( ) 

public abstract void copyData(dkXDO aXDO) throws DKException, Exception 
public abstract boolean compareData(dkXDO aXDO) throws DKException, Exception 
public short protocol ( ) 
public dkDatastore datastore( ) 
public dkDatastore getDatastore( ) 
public void setDatastore(dkDatastore ds) 

public abstract dkXDO cloneSkeleton( ) throws DKUsageEnor, Exception 

public int getAffilLatedType( ) throws DKException, Exception 

public void setArEiiatedTypc(int affiliatedType) throws DKException, Exception 

public String getMimeT\pe( ) throws DKException, Exception 

public void setMimeType(String mimeType) throws DKException, Exception 

public String getContenfiype( ) 

public void setContentType(String contentType) throws DKException, Exception 
public void addExtension(String extensionName, 

dkExtension extentionObj) throws DKException, Exception 
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public void rcmovcExtcQsioii(Stiing extras tonName) throws DKException 

public dkExtension getExtension( String extension Name) throws DKException, Exception 

public abstract byte[ ] getContentf ) throws DKException, Exception 

public abstract void setConteat(byte aByteArr[ J) throws DKException 

public abstract void setRank(int a Rank) 

public abstract int getRank( ) 

} 



The following methods are part of the dkXDO class: 
public abstract void setPid(DKPidXDO aPidXDO) throws 
DKUsage Error 

Sets the pid information of this object with the new 15 

provided pid 
Parameters: 

aPidXDO— a DKPidXDO object 
Throws: DKUsageError 
if provided pid is null 
public abstract DKPidYDO getPid( ) 

Gets a copy of the persistent ID object of this object 
Returns: 

a copy of the persistent ID object of this object 25 
public abstract DKPidXDO getPidObject( ) 

Gets a copy of the persistent ID object of this object 
Returns: 

a copy of the persistent ID object of this object 30 
public abstract void setPidObject(DKPidYDO aPidXDO) 
throws DKException 

Sets the pid information of this object with the new 
provided pid 

Parameters: 35 

aPidXDO— a DKPidXDO object 

Throws: DKException 

if provided pid is null 
public abstract void add( ) throws DKException, Exception ^ 

Adds the object content from memory to the Datastore 

Throws: DKException, 

Exception If error occurred 
public abstract void retrieves throws DKException, Excep- 
tion 45 

Retrieves the object content from the datastore to the 
memory buffer 

Throws: DKException, 

Exception If error occurred 
public abstract void update( ) throws DKException, Excep- 
tion 

Updates the object content in datastore with the content in 
memory 

Throws: DKException, S5 
Exception If error occurred 
public abstract void del( ) throws DKException Exception 
Deletes the object content from dataaore 
Throws: DKException, 

Exception If error occurred 60 
public abstract boolean isContentChanged( ) 
Checks if the part content changed (in memory). 
Returns: 

true if the object content is changed; false otherwise. 6 5 
public abstract boolean isset( ) 

Checks if the part content is set (in memory). 



Returns: 

true if the object content is set; false otherwise, 
public abstract void copyData(dkXDO aXDO) throws 
DKException, Exception 

Replaces the content of this object with the content of the 
other XDO object 

Parameters: 

adkXDO— the other XDO object 

Throws: DKException, 

Exception If error occurred 
public abstract boolean compareData(dkXDO aXDO) 
throws DKException, Exception 

Compares the content of this object with the content of the 
other XDO object 

Parameters: 

adkXDO— the other XDO object 
Throws: DKException, 
Exception If object type is different 
public shortprotocol( ) 

Returns the protocol supported by this object. 
Returns: 

the protocol "DK_JCDO" 
Overrides: 

protocol in class dkXDOBase 
public dkdatastore datastore( ) 

Gets the reference to the owner datastore object. Note: 

datastore( ) is deprecated. Replace by getdatastore. 
Returns: 

the dk Datastore object 
See Also: 
getDatastore 
public dkDatastore getDatastore( ) 

Gets the reference to the owner datastore object 
Returns: 

the dkDatastore object 
public void setDatastore(dkDatastore ds) 

Sets the reference to the owner datastore object 

Parameters: 

ds — a dkDatastore 
public abstract dkDO cloneSkeleton( ) throws 
DKUsageError, Exception 

Clones this XDO with its persistent -id only, that is, with 
its data content set to empty, 
public int getAffiliatedType( ) throws DKException, Excep- 
tion 

Gets the affiliated type of this object. An affiliated type 
could be ANNOTATION, NOTES, etc. The subclass 
need to override the behaviour of the default imple- 
mentation of this method. 

Returns: 

the affiliated type for this object, for example: DK^_CM__ 
ANNOTATION, DK_CM __NOTE, etc. 
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public void setAffliatedType(int affiliate dtype) throws Adds the extension object. 

DKException, Exception . Parameters: 

Sets the affiliated type for this object. The subclass need extensioName— the extension name 

tooverridethebehaviourofthedefaultimplementauon C xtensionObj-a source extension object 

of this method. 5 m * 

Throws: DKException, 

Parameters: . r 

cm- * *u icr * a * Exception If error occurred 

affiliated lype — the affiliated type u . r> * • /e* • • vt \ 

Jtr Jr public void removeExtension(Stnng extensionName) 

&e Also: throws DKException 

getAffiliatedtype 10 Rcmoves the extension object. 

public String getMimeType( ) throws DKException, Excep- Parameters* 

tion 

* *u \Mi\jrr * * *u* u- * n_ i_ 1 j* extensionName — the extension name 
Gets the MIME type of this object. The subclass need to 

override the behaviour of the default implementation of Throws: DKException 

this method. 1 5 If error occurred 

Returns- public dkextension getExtension(String extensionName) 

the MIME type for this object, throws DKException, Exception 

public void setMimeType(String mimeType) throws Gets the extension object. Default always throws excep- 

DKException, Exception 2Q tion. Subclass must write this method. 

Sets the MIME type for this object. The subclass need to Parameters: 

override the behaviour of the default implementation of extensionName — the extension name 

this method. Returns: 

Parameters: a dkextension object 

mimeiype— the MIME type 25 DKException, 

See Also: Exception If error occurred 

getMimetype public abstract byte[ ] getContent( ) throws DKException, 

public String getContentType( ) Exception 

Gets the content type of this object. A content type could 30 Gets mc content of this object 
be ASCII, JPG, AVI, GIF, HTML, etc. The subclass Returns- 
need to override the behavior of the default implemen- 
tation of this method. the ob J cct content as a byte array stream 

Returns- Throws: DKException, 

the content type for this object, 35 Exception If object type is different 

public void setContentType(String contentType) throws P ublic abstract void setContent(byte aByteArrf ]) throws 

DKException, Exception DKException 

Sets the content type for this object. The subclass need to Sets the content of this object with a byte array stream 

override the behaviour of the default implementation of argument 

this method. 40 Parameters: 

Parameters: aByteArr — a byte array 

contentType — the content type public abstract void setRank(int aRank) 

See Also: public abstract int getRank( ) 

getContenttype 45 8. Binary Large Objects 

public void addExtension(String extensionName, jhe dkBlob class is a common abstract class for basic 

dkExtension extensionObj) throws DKException, Excep- BLOBs in each datastore. An example class definition 

tion for dkBlob is set forth below. 



dkBlob 

package coiaibm.mm.sdkcoinmon.dkBlob 
public abstract class dkBlob 
extends dkXDO 
implements Serializable 

{ 

public abstract void add(String aFullFileName) throws DKException, Exception 
public abstract void retricvefString aFullFileName) throws DKException, Exception 
public abstract void update(String aFullFileName) throws DKException, Exception 
public abstract void del(boolean flush) throws DKException, Exception 
public abstract void getContent'IbClientFile(String afileName, 
int flleOption) throws DKException, Exception 
public abstract void 6etContentFromCHentFi]e(String afileName) throws DKException 
public abstract dkBlob concatReplace(dkBlob adkBtob) throws DKException, Exception 
public abstract dkBlob concatReplace(byte aByteArrg[ ]) throws DKException, Exception 
public abstract int length( ) throws DKException, Exception 
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public abstract int indcxOf (String astring, 

int startpos) throws DKException, Exception 
public abstract int indexOf (dkBlob adkBlob, 

int startpos) throws DKException, Exception 
public abstract String subString(int startpos, 

int alength) throws DKException, Exception 
public abstract dkBlob rernove(int startpos, 

int alength) throws DKException, Exception 
public abstract dkBlob insert(String astring, 

int startpos) throws DKException, Exception 
public abstract dkBlob insertfkdBlob adkBlob, 

int startpos) throws DKException, Exception 
public abstract void open(String afileName) throws DKException, Exception 
public abstract void setlnstanceOpcnHandlcr (String ahandler, 

boolean newSynchionousFlag) 
public abstract void setClassOpenHandler(String ahandler, 

boolean newSynchionousFlag) 
public abstract String getOpenHandler( ) 
public abstract boolean isOpenSynchronous( ) 
} 



The following methods are part of the dkBlob class: 
public abstract void add(String aFullFileName) throws 
DKException, Exception ^ 

Adds the object content from existing file to the Datastore 
Parameters: 

aFullFileName — a fully qualified path and file name, 
default is current 

30 

directory 

Throws: DKException, 
Exception If error occurred 

public abstract void retrieve(String aFullFileName) throws 
DKException, Exception 35 

Retrieves the object content from the datastore to a file 

name 
Parameters: 

aFullFileName — a fully qualified path and file name, 40 

default is current 
directory 

Throws: DKException, 

Exception If error occurred 45 
public abstract void update(String aFullFileName) throws 
DKException, Exception 

Updates the object content in datastore with a file 
Parameters: 

50 

aFullFileName — a fully qualified path and file name, 

default is current 
directory 

Throws: DKException, 

Exception If error occurred 55 
public abstract void del(boolean flush) throws 
DKException, Exception 

Deletes the object content from Datastore 
Parameters: 6° 
flush— if true the memory content-will be flush, if false - 
and content 

is not set, the object will be retreived before delete it. The 
default 

65 

is flush. 

Throws: DKException, 



Exception If error occurred 
public abstract void getContentToClientFile (String 
afileName, 

int fileOption) throws DKException, Exception 
Copies the lob data of this object to the given file 
Parameters: 

afileName — a fully qualified path with file name, default 
is current 

directory(if no path) 

fileOption — 1 will create or overwrite an existing file; 2 
will only 

create file, but will also throw an exception if the file 
already 

exists; 3 appends to an existing file 

Throws: DKException, 

Exception If error occurred 
public abstract void setContentFromClientFile(String 
afileName) throws DKException 

Replaces the lob data of this object with the contents of 
the file afilename 

Parameters: 

afileName — a fully qualified path with file name, default 
is current 

directory(if no path) 

Throws: DKException 

If error occurred 
public abstract dkBlob concatReplace(dkBlob adkBlob) 
throws DKException, Exception 

Concatenates this object content with another object con- 
tent the results of the concatenation replaces the exist- 
ing contents of this object. Note: concatReplace( ) is 
deprecated. 

Parameters: 

adkBlob — another dkBlob object 
Returns: 
a dkBlob object 
public abstract dkBlob concatReplace(byte aByteArrgf ]) 
throws DKException, Exception 

Concatenates this object content with another stream the 
results of the concatenation replaces the existing con- 
tents of this object Note: concatReplace( ) is depre- 
cated. 
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Parameters: 

aByteArrg — a byte array stream 
Returns: 
a dkBlob object 
public abstract int length( ) throws DKException, Exception 
Gets the length of this object content in memory 
Returns: 

a byte length of this object content in memory 
public abstract int indexOf(String astring, 

int startpos) throws DKException, Exception 

Returns the byte ofiset of the first occurrence of the search 
argument within this object, starting the search at offset 
startPos. If the search argument is not found, return 0. 
Note: indexOf( ) is deprecated. 

Parameters: 

astring — the search string argument 
startpos — the offset position start to search 
Returns: 

the byte offset of the first occurrence of the search 

argument; return 0 
if the search argument is not found 
public abstract int indexOf(dkBlob adkglob, 
int startpos) throws DKException, Exception 
Returns the byte ofiset of the first occurrence of the search 

argument within this object, starting the search at offset 

startPos. If the search argument is not found, return 0. 

Note: indexOf( ) is deprecated. 
Parameters: 

adkBlob — the lobData of this dkBlob is the search argu- 
ment 

starpos — the offset position start to search 
Returns: 

the byte offset of the first occurrence of the search 

argument; return 0 
if the search argument is not found 
public abstract String subString(int startpos, 
int alength) throws DKException, Exception 
Returns a string object containing a substring of the lob 

data of this object. The substring will be taken starting 

at byte offset startpos, and extracting alength bytes. 

Note: subString( ) is deprecated. 
Parameters: 

startpos — the byte offset position start to extract 

alength — the length to extract 

Returns: 

a string object 
public abstract dkBlob remove (int startpos, 

int alength) throws DKException, Exception 

Deletes the portion of the lob data of this object starting 
at startpos for alength bytes. Note: remove( ) is dep- 
recated. 

Parameters: 

startpos — the byte offset position start to delete 
alength — the length to delete 
Returns: 
a dkBlob object 
public abstract dkBlob insert(String astring, 
int startpos) throws DKException, Exception 
Inserts the argument data, following position startpos in 
the lob data of this object. Note: insert( ) is deprecated. 



Parameters: 

astring — the argument string data 
startpos — the byte offset position start to insert 
5 Returns: 

a dkBlob object 
public abstract dkBlob insert(dkBlob adkBlob, 
int startpos) throws DKException, Exception 
10 Inserts the argument data, following position startpos in 
the lob data of this object. Note: insert( ) is deprecated. 
Parameters: 

adkBlob — the lobData of this dkBlob is the argument data 
15 startpos — the byte offset position start to insert 

Returns: 

a dkBlob object 
public abstract void open(String afileName) throws 
20 DKException, Exception 

Unloads the object content to a file afileName provided by 
the application and then synchronously invoking a 
default handler against the file. 
2$ Parameters: 

afileName — a provided file name 
Throws: DKException, 
Exception If error occurred 
30 public abstract void setInstanceOpenHandler(String 
ahandler, 

boolean newSynchronousFlag) 

Sets the executable handler program name and whether 
35 this handler should be invoked synchronously or asyn- 
chronously for this object instant 
Parameters: 

ahandler — the handler program name to view the content 
newSynchronousFlag — true for synchronous process; 
40 false otherwise. 

public abstract void setQassOpenHandler(String ahandler, 
boolean newSynchronousFlag) 

Sets the executable handler program name and whether 
this handler should be invoked synchronously or asyn- 
chronously for this object class 
Parameters: 

ahandler — the handler program name to view the content 
50 newSynchronousFlag — true for synchronous process; 
false otherwise, 
public abstract String getOpenHandler( ) 

Gets the current program name of the handler for this 
55 object instance 
Returns: 

the handler program name 
public abstract boolean isOpenSynchronous( ) 
60 Gets the current synchronization property 
Returns: 

TRUE or FALSE for the handler 
DKBlobDL is a specific version of DKBlob for a Digital 
65 Library/Visual Info. Note that for DKBlobDL, a blob 
(XDO) represents a part object of DL. An example 
class definition for DKBlobDL is set forth below. 
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DKBIobDL 

package com.ibm.mm.sdkcommoiLdkBlobDL 
public class DKBIobDL extends dkBlob 

implements DKConstant, DKConstantDL, DKMessageld, Serializable 

APPEND 

checkedMultistreamFlag 

isMul tistreamB lob 

isMultistreamTnOS 

mtocLobData 

NOOVERWRTTE 

OVERWRITE 

streamLobData 

strcamName 

streamReptype 

{ 

public DKBlobDL(dkDatastore aDatastore) throws DKUsageError, Exception 
public DKBlobDL(dkDatastore aDatastoie, 

byte aBytcArr[ ]) throws DKException, Exception 
public DKBlobDL(DKBlobDL, aDKBlobDL) throws DKException 
public String getObjectType( ) 
public void deletingValue( ) 
public boolean isGontentChanged( ) 
public boolean isSet( ) 
public boolean isNull( ) 
public boolean setNull( ) 

public boolean equals (dkXDOBase adtXDOBase) throws DKException 
public boolean notEqual(dkXDOBase adkXDOBase) throws DKException 
public DKPxdXDO getPid( ) 

public void setPid(DKPidXDO aDKPid) throws DKUsageError 
public DKPidXDO getPidObject( ) 

public void sctPidObject(DKPidXDO aPidXDO) throws DKException 

public void add( ) throws DKException, Exception 

public void add(String a FullFileName) throws DKException, Exception 

public void retrievef ) throws DKException, Exception 

public void retrieve(String aFileName) throws DKException, Exception 

public void update(String aFileName) throws DKException, Exception 

public void update( ) throws DKException, Exception 

public void del( ) throws DKException, Exception 

public void del(boolean flush) throws DKException, Exception 

public void copyData(dkXDO adkXDO) throws DKException, Exception 

public boolean compareData(dkXDO adkXDO) throws DKException, Exception 

public void setContent(byte aByteArray[ J) 

public byte[ ] getContent( ) throws DKException, Exception 

public void getContentToClicntFile(String anleNarne, 

int fileOption) throws DKException, Exception 
public void setContentFiomClientFile (String afUeName) throws DKException 
public dkBlob concatReplace(dkBlob adkBlob) throws DKException, Exception 
public dkBlob concatReplace(byte aByteArrf j) throws DKException, Exception 
public int length( ) throws DKException, Exception 
public int indexOf(String astring, 

int startpos) throws DKException, Exception 
public int indexOf (dkBlob adkBlob, 

int startpos) throws DKException, Exception 
public String subString(int startpos, 

int alength) throws DKException, Exception 
public dkBlob remove(int startpos, 

int alength) throws DKException, Exception 
public dkBlob insert(String astring, 

int startpos) throws DKException, Exception 
public dkBlob insert(dkBlob adkBlob, 

int startpos) throws DKException, Exception 
public void open( ) throws DKException, Exception 
public void open(String afileName) throws DKException, Exception 
public void setInstanceOpenHandler(String ahandler, 

boolean newSynchronousFlag) 
public void setQassOpenHandler(String ahandlei, 

boolean newSynchronousFlag) 
public String getOpenHandler( ) 
public boolean isOpenSynchronous( ) 
public String getRepType( ) 
public void setRepType(String aRType) 
public String getltemld( ) 
public void setItemId(String altemld) 
public int getContentClass( ) 
public void setContentClass(int aCClass) 
public int getAffiIiatedType( ) throws DKException, Exception 
public void setAffiliatedTypejmt aAType) throws DKException, Exception 
public DKAnnotation getAffiliatedData( ) 



11/28/2003, EAST Version: 1.4.1 



US 6,370,541 Bl 
89 90 

-continued 



public void setAffiliatedTVpe(DKAmiotation apAData) 

public String getSearchEngine( ) throws DKException, Exception 

public void setSearchEngine(String aSearchEngine) throws DKException, Exception 

public String getSearchlndex( ) throws DKException, Exception 

public void setSearchlndex (String aSearchlhdex) throws DKException, Exception 

public String getSearchInfo( ) throws DKException, Exception 

public void getSearchInfo(String aSearchlnfo) throws DKException, Exception 

public boolean get[ndexFlag( ) 

public void setlndexFlag (boolean aFlag) 

public DKBlobDL concatenate (DKBlobDL aDKBlobDL) throws DKException, Exception 
public DKBlobDL concatcnate(byte aByteArr[ ]) throws DKException, Exception 
public DKBlobDL subLob(int startpos, 

int alength) throws DKException, Exception 
public void setRank(int a Rank) 
public int getRank( ) 

public String getMimeType( ) throws DKExce-ption, Exception 

public String mimeType( ) throws DKException, Exception 

public void setTbBeIndexed( ) throws DKException, Exception 

public String getCrcatedTimestamp( ) throws DKException, Exception 

public String getUpdatedTImestamp( ) throws DKException, Exception 

public int getRetrievalActionf ) throws DKException, Exception 

public void setRetrievalAction(int aRetriveAction) throws DKException, Exception 

public int getSize( ) throws DKException, Exception 

public Object getOptton(int option) throws DKException, Exception 

public void setOption(int option, 

Object value) throws DKException, Exception 
public void setExtension(String extensionName, 

dkExtension extensionObj) throws DKException, Exception 
public void addExtension(String extensionName, 

dkExtension extensionObj) throws DKException, Exception 
public dkExtension getExtension(String extensionName) throws DKException, Exception 
public void rcmoveExtension(String extensionName) throws DKException 
public boolean isCategoryOf(int categoryName) throws DKException, Exception 
public int retrieveObjectState(int object) throws DKException, Exception 
public void changeStorage( ) throws DKException, Exception 
public int getPart[d( ) 
public void sctPartId(int partld) 

public String[ ] listStreamName( ) throws DKException, Exception 

public byte[ ]getStreamContent(String sName) throws DKException, Exception 

public void setStreamContent(String sName, 

byte aByteArray[ ]) throws DKException, Exception 

public long streamLength(String sName) throws DKException, Exception 

public boolean isMultiStreamBlob( ) 

public boolean isMultiStreamFlagSet( ) 

} 



The following methods are part of the DKBlobDL class: 
public DKBlobDL(dkDatastore aDatastore) throws 
DKUsageError, Exception 

Constructs the blob and defers initialization until imple- 
mentation methods are called. 

Parameters: 

aDatastore — a DKDatastoreDL representing the associ- 
ated DL Datastore 
Throws: DKUsageError, 
Exception If invalid datastore type 
public DKBlobDL(dkDatastore aDatastore, 

byte aByteArr[ ]) throws DKException, Exception 
Constructs the blob and set the object's content. 
Parameters: 

aDatastore — a DKDatastoreDL representing the associ- 
• ated DL datastore 

aByteArr — a byte array to be set as this object's content 

Throws: DKException, 

Exception If error occurred 
public DKBlobDL(DKBlobDL aDKBlobDL) throws 
DKException 

Copy constructor. 

Parameters: 

aDKBlobDL — an instance of DKBlobDL 



Throws: DKException 
If error occurred 
public String getObjecfiype( ) 
Gets the object type. 
Returns: 

the object type "DKBlobDL" 
Overrides: 

getObjectType in class dkXDOBase 
public void deletingvalue( ) 

Deletes value, this function performs as setNull in this 

class. Note: deletingvalue( ) is deprecated. 
Overrides: 

deletingValue in class dkXDOBase 
public boolean isContentChanged( ) 

Checks if the part content changed (in memory). 
Returns: 

true if the object content is changed; false otherwise. 
Overrides: 

isContentChanged in class dkXDO 
public boolean isset( ) 

Checks if the part content is set (in memory). 
Returns: 

true if the object content is set; false otherwise. 
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Overrides: 

isSet in class dkXDO 
public boolean isNull( ) 

Checks if the part content is null (in memory). 
Returns: 

true if the object content is null; false otherwise. 
Overrides: 

isNull in class dkXDOBase 
public void setNull( ) 

Sets the part content to null (in memory). 
Overrides: 

setNull in class dkXDOBase 
public boolean equals(dkXDOBase adkXDOBase) throws 
DKException 

Checks if the xdo objects have same type, pid, content and 
indexed by same search engine. Note: equals( ) is 
deprecated. 

Parameters: 

adkXDOBase — an instance of dkXDOBase 
Returns: 

true if the objects have same type, pid, content and search 

index false otherwise. 
Throws: DKException 
If objects are not the same class 
Overrides: 

equals in class dkXDOBase 
public boolean notEqual(dkXDOBase adkXDOBase) 
throws DKException 

Checks if the xdo objects is not equal. Note: notEqual( ) 
is deprecated. 

Parameters: 

adkXDOBase — an instance of dkXDOBase 
Returns: 

true if the objects do not have same type, pid, content and 

search index 
false otherwise. 
Throws: DKException 
If objects are not the same class 
Overrides: 

notEqual in class dkXDOBase 
public DKPidXDO getPid( ) 

Gets a copy of the persistent ID object of this DKBlobDL 

object. Note: getPid( ) is deprecated. Replace by 

getPidObject( ). 
Returns: 

a copy of the persistent ID object of this DKBlobDL 

object 
Overrides: 

getPid in class dkXDO 
See Also: 
getPidobject 

public void setPid(DKPidXDO aDKPid) throws DKUsag- 
eError 

Sets the pid information of this object with the new 
provided pid. Note: setPid( ) is deprecated. Replace by 
setPidObject(DKPidXDO aPidXDO). 

Parameters: 

aDKPid—* DKPidXDO object 
Throws: DKUsageError 
If provided pid is null 
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Overrides: 

setPid in class dkXDO 
See Also: 
setPidobject 
public DKPidXDO getPidObject( ) 

Gets a copy of the persistent ID object of this object 
Returns: 

a copy of the persistent ID object of this object 
Overrides: 

getPidObject in class dkXDO 
public void setPidObject(DKPidXDO aPidYDO) throws 
DKException 

Sets the pid information of this object with the new 
provided pid 

Parameters: 

aPidXDO— a DKPidXDO object 
Throws: DKException 
If provided pid is null 
Overrides: 

setPidObject in class dkXDO 
public void add( ) throws DKException, Exception 
Adds the object content from memory to the Datastore 
Throws: DKException, 
Exception If error occurred 
Overrides: 

add in class dkXDO 
public void add(String aFullFileName) throws 
DKException, Exception 

Adds the object content from existing file to the Datastore 

Parameters: 

aFullFileName — a fully qualified path and file name, 

default is current 
directory 

Throws: DKException, 
Exception If error occurred 
Overrides: 
add in class dkBlob 
public void retrieve( ) throws DKException, Exception 
Retrieves the object content from the datastore to the 

memory buffer 
Throws: DKException, 
Exception If error occurred 
Overrides: 

retrieve in class dkXDO 
public void retrieve(String aFileName) throws 
DKException, Exception 

Retrieves the object content from the datastore to a file 
name 

Parameters: 

aFileName — a fully qualified path and file name, default 

is current 
directory 

Throws: DKException, 
Exception If error occurred 
Overrides: 

retrieve in class dkBlob 
public void update(String aFileName) throws DKException, 
Exception 

Updates the object content in datastore with a file 
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Parameters: 

aFileName — a fully qualified path and file name, default 

is current 
directory 

Throws: DKException, 
Exception If error occurred 
Overrides: 

update in class dkBlob 
public void update( ) throws DKException, Exception 10 
Updates the object content in datastore with the content in 

memory 
Throws: DKException, 

Exception If error occurred 15 
Overrides: 

update in class dkXDO 
public void del( ) throws DKException, Exception 
Deletes the object content from Datastore 

20 

Throws: DKException, 

Exception If error occurred 

Overrides: 

del in class dkXDO 
public void del(boolean flush) throws DKException, Excep- 25 
tion 

Deletes the object content from Datastore 
Parameters: 

flusli — if true the memory content will be flush, if false 30 
and content 

is not set, the object will be retreived before delete it The 

default 
is flush. 

Throws: DKException, 35 

Exception If error occurred 

Overrides: 

del in class dkBlob 
public void copyData(dXDO adkXDO) throws 40 
DKException, Exception 

Replaces the content of this object with the content of the 
other XDO object 

Parameters: 

adkXDO— the other XDO object 45 
Throws: DKException, 
Exception If error occurred 
Overrides: 

copyData in class dkXDO 50 
public boolean compareData(dkXDO adkXDO) throws 
DKException, Exception 

Compares the content of this object with the content of the 
other XDO object 

Parameters: 

adkXDO— the other XDO object 

Throws: DKException, 

Exception If object type is different 

Overrides: 60 
compareData in class dkXDO 
public void setContent(byte aByteArray[ ]) 

Sets the content of this object with a byte array stream 

argument 65 
Parameters: 

aByteArray — a byte array 
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Overrides: 

setContent in class dkXDO 
public byte[ ] getContent( ) throws DKException, Exception 
Gets the content of this object 
Returns: 

the object content as a byte array stream 

Throws: DKException, 

Exception If object type is different 

Overrides: 

getContent in class dkXDO 
public void getContentToClientFile(String afileName, 
int fileOption) throws DKException, Exception 
Copies the lob data of this object to the given file 
Parameters: 

afileName — a fully qualified path with file name, default 

is current 
directory(if no path) 

fileOption — 1 will create or overwrite an existing file; 2 
will only create file, but will also throw an exception if 
the file already exists; 3 appends to an existing file 

Throws: DKException, 

Exception If error occurred 

Overrides: 

getContentToClientFile in class dkBlob 
public void setContentFromClientFile(String afileName) 
throws DKException 

Replaces the lob data of this object with the contents of 
the file afilename 

Parameters: 

afileName — a fully qualified path with file name, default 

is current 
directory(if no path) 
Throws: DKException 
If error occurred 
Overrides: 

setContentFromCIientFile in class dkBlob 
public dkBlob concatReplace(dkBlob adkBlob) throws 
DKException, Exception 
Concatenates this object content with another object con- 
tent the results of the concatenation replaces the exist- 
ing contents of this object. Note: concatReplace( ) is 
deprecated. 
Parameters: 

adkBlob — another dkBlob object 

Returns: 

a dkBlob object 

Overrides: 

concatReplace in class dkBlob 
public dkBlob concatReplace(byte aByteArr[ ]) throws 
DKException, Exception 
Concatenates this object content with another stream the 
results of the concatenation replaces the existing con- 
tents of this object. Note: concatReplace( ) is depre- 
cated. 
Parameters: 

aByteArr — a byte array stream 
Returns: 

a dlkBlob object 
Overrides: 

concatReplace in class dkBlob 
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public int length( ) throws DKException, Exception 
Gets the length of this object content in memory 
Returns: 

a byte length of this object content in memory 5 
Overrides: 

length in class dkBlob 
public int index Of (String astring, 

int startpos) throws DKException, Exception 

Returns the byte offset of the first occurrence of the search 10 
argument within this object, starting the search at offset 
startPos. If the search argument is not found, return 0, 
Note: indexOf( ) is deprecated. 

Parameters: 15 

astring — the search string argument 

starpos — the offset position start to search 

Returns: 

the byte offset of the first occurrence of the search 

argument; return 0 20 
if the search argument is not found 
Overrides: 

indexOf in class dkBlob 
public int indexOf (dkBlob adkBlob, 25 

int startpos) throws DKException, Exception 

Returns the byte offset of the first occurrence of the search 
argument within this object, starting the search at offset 
startPos. If the search argument is not found, return 0. 
Note: indexOf( ) is deprecated. 30 

Parameters: 

adkBlob — the lobData of this dkBlob is the search argu- 
ment 

startpos — the offset position start to search 35 
Returns: 

the byte offset of the first occurrence of the search 

argument; return 0 
if the search argument is not found 

Overrides: 40 

indexOf in class dkBlob 
public String subString(int startpos, 

int alength) throws DKException, Exception 

Returns a string object containing a substring of the lob 45 
data of this object. The substring will be taken starting 
at byte offset startpos, and extracting alength bytes. 
Note: subString( ) is deprecated. 

Parameters: 

startpos — the byte offset position start to extract 50 

alength — the length to extract 

Returns: 

a string object 

Overrides: 55 
substring in class dkBlob 
public dkBlob remove(int startpos, 

int alength) throws DKException, Exception 
Deletes the portion of the lob data of this object starting 
at startpos for alength bytes. Note: remove( ) is dep- 60 

recated. _ .. 

Parameters: 

startpos — the byte offset position start to delete 

alength— the length to delete 65 

Returns: 

a dkBlob object 
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Overrides: 

remove in class dkBlob 
public dkBlob insert(String astring, 
int startpos) throws DKException, Exception 
Inserts the argument data, following position startpos in 
the lob data of this object. Note: insert( ) is deprecated. 
Parameters: 

astring — the argument string data 

startpos — the byte offset position start to insert 

Returns: 

a dkBlob object 

Overrides: 

insert in class dkBlob 
public dkBlob insert(dkBlob adkBlob, 

int startpos) throws DKExceptioo, Exception 
Inserts the argument data, following position startpos in 
the lob data of this object. Note: insert( )is deprecated. 
Parameters: 

adkBlob — the lobData of this dkBlob is the argument data 

startpos — the byte offset position start to insert 

Returns: 

a dkBlob object 

Overrides: 

insert in class dkBlob 
public void open( ) throws DKException, Exception 
Unloads the object content to a client file with a system 

generated name and then synchronously invoking a 

default handler against the file. 
Throws: DKException, 
Exception If error occurred 
Overrides: 

open in class dkXDOBase 
public void open(String afileName)throws DKException, 
Exception 

Unloads the object content io a file afileName provided by 
the application and then synchronously invoking a 
default handler against the file. 

Parameters: 

afileName — a provided file name 
Throws: DKException, 
Exception If error occurred 
Overrides: 

open in class dkBlob 
public void setInstanceOpenHandler(String ahandler, 
boolean newSynchronousFlag) 

Sets the executable handler program name and whether 
this handler should be invoked synchronously or asyn- 
chronously for this object instant 

Parameters: 

ahandler — the handler program name to view the content 
newSynchronousFlag — true for synchronous process; 

false otherwise. 
Overrides: 

set InstanceOpenHandler in class dkBlob - 
public void setClassOpenHandler(String ahandler, 
boolean newSynchronousFlag) 

Sets the executable handler program name and whether 
this handler should be invoked synchronously or asyn- 
chronously for this object class 
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Parameters: 

ahandler — the handler program name to view the content 
newSynchronousFlag — true for synchronous process; 

false otherwise. 
Overrides: 

setClassOpenHandler in class dkBlob 
public String getOpenHandler( ) 

Gets the current program name of the handler for this 

object instance 
Returns: 

the handler program name 
Overrides: 

getOpenHandler in class dkBlob 
public boolean isOpengynchronous( ) 

Gets the current synchronization property 
Returns: 

TRUE or FALSE for the handler 
Overrides: 

isOpenSynchronous in class dkBlob 
public String getRepType( ) 

Gets the DL representation type of the object content 
Returns: 

the DL representation type of the object content 
public void setRepType(String aRType) 

Sets the DL representation type of the object content 

Parameters: 30 

aRType — the DL representation type of the object content 
public String getltemld( ) 

Gets the DL item id of the object content 

Returns: 35 

the DL item id of the object content 
public void setItemId(String altemld) 

Sets the DL item id of the object content 

Parameters: 

aRType — the DL item id of the object content 
public int getContentClass( ) 

Gets the content class of the object 
Returns: 

the content class of the object 45 
public void setContentClass(int aCClass) 
Sets the content class of the object 
Parameters: 

aCClass — the content class of the object 50 
public int getAffiliatedType( ) throws DKException, Excep- 
tion 

Gets the affiliated type of the object if 
DK_ANNOTATION, the getExtension 
("DKAnnotationDL") should point to DKAnnota- 55 
tionDL 

Returns: 

the affiliated type of the object 

Overrides: 60 

getAfEliatedType in class dkXDO 
public void setAffiliatedType(int aAType) throws 
DKException, Exception 

Sets the affiliated type of the object g5 
Parameters: 

aAType — the affiliated type of the object 
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Overrides: 

setAffiliatedType in class dkXDO 

getAffiliatedData 
public DKAnnotation getAffliatedData( ) 

Gets the affiliated data of this object, if the affiliatedType 
is DK_ANNOTATION, this should get the DKAnno- 
tation object. Note: getAffiliatedData( ) is deprecated. 
Replace by getExtension(String extensionName). 

Returns: 

a DKAnnotation object contains the annotation data infor- 
mations 
See Also: 
getExtension 

public void setAfffliatedData(DKAnnotation apAData) 
Sets the affiliated data of this object, if the affiliatedType 
is DK_ANNOTATION, this should be provided. Note: 
setAflfiliatedData( ) is deprecated. Replace by 
setExtension(..). 
Parameters: 

apAData — a DKAnnotation object contains the annota- 
tion data 
informations 
See Also: 
setExtension 

public String getSearchEngine( ) throws DKException, 
Exception 

Gets search engine name. Note: getSearchEngine( ) is 
deprecated. Replace by 

DI^earchEngineInfoDL.getSearchEngrne( ). 

Returns: 

the search engine name; SM for text search, QBIC for 

image search 
Throws: DKException, 
Exception If error occurred 
See Also: 
getExtension 

public void setSearchEngine(String aSearchEngine) throws 
DKException, Exception 
Sets the search engine name. Note: setSearchEngine( ) is 
deprecated. Replace by 

DKSearchEngineInfoDL.setSearchEngine(..) 
Parameters: 

aSearchEngine — the search engine name; SM for text 

search, QBIC for 
image search 
Throws: DKException, 
Exception If error occurred 
See Also: 
setExtensioQ 

public String getSearchIndex( ) throws DKException, 
Exception 

Gets the search index; ie "SearchService-IndexNarne" 
name. Note: getSearchIndex( ) is deprecated. Replace 
by DKSearchEngineInfoDL.getSearchIndex( ). 

Returns: 

the search index name 
Throws: DKException, 
Exception If error occurred 
See Also: 
getExtension 

public void setSearchIndex(String aSearchlndex) throws 
DKException Exception 
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Sets the search index; ie "SearchService-IndexNa^le ,, Returns: 

name. Note: setSearchIndex( ) is deprecated. Replace a new DKBlobDL object containing the result 

by DKSearchEngineInfoDL.setSearchIndex(..). Throws: DKException, 

Parameters: Exception If error occurred 

aSearchlndex — the search index name like 5 public DKBlobDL concatenate(byte aByteArr[ ]) throws 

"SearchService-IndexName" DKException, Exception 

Throws: DKException, Concatenates this object content with another stream and 

Exception If error occurred returns a new DKBlobDL object containing the result. 

See Also- 10 Note: concatenate( ) is deprecated. 

. Parameters: 
setExtension 

public String getSearchInfo( ) throws DKException, Excep- aByteArr— a byte array stream 

tion Returns: 

Gets the search information value; a three chars code, a new DKBlobDL object containing the result 

valid in the NLS language table that identifies the 15 Throws: DKException, 

language, (ie. ENU is US English, JAP is Japanese..). Exception If error occurred 

Note: getSearchInfo( ) is deprecated. Replace by public DKBlobDL subLob(int startpos, 

DKSearchiEngineInfoDUgetSearchInfo( ). j nt alength) throws DKException, Exception 

Returns: ^ Similar to substring, but returns the substring data in 

the search infomation value form of a new DKBlobDL object. Note: subLob( ) is 

Throws: DKException, deprecated. 

Exception If error occurred Parameters: 

See Also* startpos — the byte offset position to start 

getExtension 25 alen g th — ^ e length of bytes to obtain 

public void setSearchlnfo (String aSearchlnfo) throws Returns: 

DKException, Exception a new DKBlobDL object containing the result 

Sets the search infomation value; a three chars code, valid Throws: DKException, 

in the NLS language table that identifies the language. 30 Exception If error occurred 

(ie. ENU is US English, JAP is Japanese..). Note: public void setRank(int aRank) 

setSearchInfo( ) is deprecated. Replace by Sets the ranking value of a query 

DKSearchEngineInfoDL.setSearchInfo(..). Parameters: 

Parameters: aRank — a ranking value 

aSearchlnfo — the three chars code, valid in the NLS 35 Overrides: 

language table setRank in class dkXDO 

Throws: DKException, public int getRank( ) 

Exception If error occurred Gets the ranking value of a query 

See Also: 40 Returns: 

setExtension a ranking value 

public boolean getIndex.Flag( ) Overrides: 

Gets the flag that indicates a part object is indexed by a getRank in class dkXDO 

search engine. Note: 45 public String getMimeType( ) throws DKException, Excep- 

get!ndexFlag( ) is deprecated. Replace by isCategoryOf Uon 

(..) method of this class. Gct s the MIME type represents this object's contentClass 

Returns: Returns: 

true if a part object is indexed by a search engine false tne MIME type 

otherwise. 50 Throws: DKException, 

See Also: Exception If error occurred 

isCategoryOf Overrides: 

public void setIndexFlag(boolean aFlag) ^ getMimeType in class dkXDO 

o**ua *u # • J- ♦ ji_ public String mimeType( ) throws DKException, Exception 

Sets the flag that indicates a part object is indexed by a 55 r n . Jr w A \, ' 4 * 

search engine. Note: setIndexFlag( ) is deprecated. Gets MIME ^ re P resents this object's contentClass 



Parameters: 



Returns: 

. . the MIME type 

aflag-a flag to mdicate the part object is indexed by a Throws; DKException, 
search engine r 



public DKBlobDL concatenate(DKBlobDL aDKBlobDL) 60 5? Cept £ n tw C c 

throws DKException, Exception * ^ VOld *™B*«k"*( ) throws DKException, Excep- 

Concatenates this object content with another object con- Indexes an existing part object by search engine 
tent and returns a new DKBlobDL object containing the Throws' DKException, 

result. Note: concatenate( ) is deprecated. fi5 Exception If error occurred 

Parameters: publ j c Strmg ge tCreatedTimestamp( ) throws DKException, 

aDKBlobDL — another DKBlobDL object Exception 
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Gets the data & time that the object was created 
Returns: 

the data & time that the object was created 

Throws: DKException, 5 

Exception If error occurred 
public String getUpdatedTimestamp( ) throws 
DKException, Exception 

Gets the data & time that the object was updated 

Returns: 10 

the data & time that the object was updated 

Throws: DKException, 

Exception If error occurred 
public int getRetrievalAction( ) throws DKException, 15 
Exception 

Gets the retrieval option to perform the retrieve action. 

Note: getRetrievalAction( ) is deprecated. Replace by 

getOption(int option). 
Returns: 20 
the retrieval option 
Throws: DKException, 
Exception If error occurred 

See Also: 25 
getOption 

public void setRetrievalAction(int aRetriveAction) throws 
DKException, Exception 

Note: setRetrievalAction( ) is deprecated Replace by 
setOption(int option, Object value) 30 

Sets the retrieval option to perform the retrieve action. 

Parameters: 

the — retrieval option 

Throws: DKException, 

Exception If error occurred 

See Also: 

setOption 

public int getSize( ) throws DKException, Exception 

Gets the size of this object without retrieve object content. 40 

Returns: 

the object size 

Throws: DKException, 

Exception If error occurred 45 
public Object getOption(int option) throws DKException, 
Exception 

Gets the delete or retrieval option to perform the delete or 
retrieve action. 

Returns: 50 
a retrieval or delete option 
Throws: DKException, 
Exception If error occurred 
public void setOption(int option 55 
Object value) throws DKException, Exception 
Sets the delete or retrieval option to perform the delete or 

retrieve action. 
Parameters: 

option — an option 60 
The valid options are: 

DK_OPT_DL_DELETE_OPTION: for delete 
DK_OPT_DL_RETRIEVAL_ACTION: for retrieve 
value — the option value * 65 
For DK„OPT_DL_DELETE_OPTION, the valid val- 
ues are: 
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For Non-media objects only: 

DK_DELETE _1TEM 

Delete item if no more part left in the item. 

Die_DELETE_OBJECT_ONLY(default if not set) 

Don't delete the item, even if there is no more part left in 

the item. 

For Media objects only: 

DK_DELETE NO_DROPITEM__MEDIA _AVAIL 
Don't delete the item if there is no part left in the item. 
Cannot delete media parts (media objects) when they are 

in 
use. 

DK_DELETE NO_DROPITEM_MEDIA_INUSE 
Don't delete the item, even if there is no part left in the 
item. User can delete media parts (media objects), even if 
they are in use. 

DK_DELETE_DROPITEM_MEDIA__AVAlL 
Delete the item if there is no part left in the item. Cannot 
delete media parts (media objects) when they are in use. 
DK_DELETE_DROPITEM_MEDIA_INUSE 
Delete the item if there is no part left in the item. Can 
delete media parts (media objects), even if they are in use. 
For DK_OPT_DL_RETRIEVAL ^ACTION, the valid 

values are: 
DK_RETRIEVAL_GET_JT 
DK_RETR1EVAL_GET_IT_PREFETCH 
DK_RETRIEVAL_NO_MOUNT 
DK_RETRIEVAL_NO_MOUNT_PREFETCH 
DK_RETRIEVAL_STAGE_IT 
DK_RETRIEVAL_STAGE_JT_PREFETCH 
Throws: DKException, 
Exception If error occurred 
public void setExtension(String extensionName, 

dkExtension extensionObj) throws DKException, Excep- 
tion 

Sets the extension object. 
Parameters: 

extensionName — the extension name 
The valid extension names are: 
DKSearchEnginelnfoDL 

For an annotation object, user needs to set this extension 
object 

to hold the affiliated informations. 
DKAnnotationDL 

For a search indexed object, user needs to set this exten- 
sion 

object to hold the search indexed informations. 
DKMediaStreamlnfoDL 

For a media object, user needs to set this extension object 
to 

hold the media user data. 
DKStorageManagelnfoDL 

If user wants to associate this part with different storage 
collection name, user needs to set this extension object to 
hold 

the storage collection information. 
extensionObj — a source extension object 
Throws: DKException, 
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Exception If error occurred 
public void addExtension(String extensionName, 

dkExtension extensionObj) throws DKException, Excep- 
tion 

Adds the extension object. 
Parameters: 

extensionName — the extension name 
extensionObj — a source extension object 
Throws: DKException, 
Exception If error occurred 
Overrides: 

addExtension in class dkXDO 
public dkExtension getExtension(String extensionName) 
throws DKException, Exception 

Gets the extension object. 

Parameters: 

extensionName — the extension name 

The valid extension names are: 

DKSearchEnginelnfoDL 

DKAnnotationDL 

DKMediaStreamlofoDL 

DKStorageManagelnfoDL 

Returns: 

a dkExtension object 
Throws: DKException, 
Exception If error occurred 
Overrides: 

getExtension in class dkXDO 
public void removeExtension(String extensionName) 
throws DKException 

Removes the extension object. 

Parameters: 

extensionName — the extension name 

The valid extension names are: 

DKSearchEnginelnfoDL 

DKAnnotationDL 

DKMediaStreamlnfoDL 

DKStorageManagelnfoDL 

Throws: DKException 

If error occurred 

Overrides: 

removeExtension in class dkXDO 
public boolean isCategoryOf(int categoryName) throws 
DKException, Exception 

Checks the object category. 

Parameters: 

categoryName — the category name 
The valid category names are: 
DK_MEDIA^_OBJECT 
DieJNDEXED„object 
Returns: 

true if the object is the specified category; false otherwise. 

Throws: DKException^ 

Exception If error occurred 
public int retrieveObjectState(int object) throws 
DKException, Exception 

Retrieves the state of search indexed object or media 
object 
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Parameters: 

object — the type of object 
The valid input are: 
DK_MEDIA_OBJECT 
DK__INDEXED_pbj ect 
Returns: 
the object state 

For media object, the valid states are: 
1: Pending, load in progress 
2: Load completed successfully 
3: Load failed 

For search indexed object, the valid states are: 
15 256: to be updated 
512: to be deleted 
769: queued update 
770: queued delete 
20 1024: indexed 

Throws: DKException, 
Exception If error occurred 
public void changeStorage( ) throws DKException, Excep- 
tion 

Changes the system-managed storage (SMS) criteria for 
an object. The collection name, management class 
name and storage class name will be all converted to 
upper case by the system. These names must be valid 
30 on the object server where user stores the object. If user 
changes the collection name and specify a null string as 
the class name, the function places the object in the 
default class for the specified collection. User cannot 
move the object from one server to another using this 
35 function, therefore user cannot change the StoreSite. If 
the change causes any physical movement of the 
object, it might be deferred until the storage manage- 
ment cycle runs on the server. 
Throws: DKException, 
40 Exception If error occurred 
public int getPartId( ) 

Gets the part id of this XDO 
Returns: 
45 the part id 

public void setPartId(intpartId) 
Gets the part id of this XDO 
Returns: 
the part id 

50 public String[ ] listStreamName( ) throws DKException, 
Exception 

Returns a string array which contains a listing of all 
stream names in the current content, returns null if 
(multi)stream content not set (available). Note: if the 
content is not set, will attempt to retrieve the content 
from the object server. 
Returns: 

string array containing current stream names, else null. 
60 Throws: DKException 

(Exception) if error occurs, 
public by te[~] getStreamContent(String sName) throws" 
DKException, Exception 

Returns the content of the stream specified by sName. If 
65 the stream does not exist throws DKException. If this 
is not a (multi)stream object then returns content of 
primary stream (lobData). 
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Parameters: 

sName— name of string to retrieve content. 
Returns: 

byte array stream content corresponding to sName, else 3 
content of 

primary stream. 

Throws: DKException • 1Q 

is thrown if this is a (multi)stream object and stream does 
not exists 

with name sname. 

15 

public void setStreamContent(String sNarne, 

byte aByteArray[ J) throws DKException, Exception 

20 

Sets the content of the stream specified by sName to 
aByteArray. If the stream does not exist a new stream 
is added with streamName=sName and contents 
aByteArray. If this is not a (multi)stream object, the 
primary stream content is set to aByteArray instead. 25 

Parameters: 

sName — name of stream to set content. 
aByteArray — content to set. 

30 

Throws: DKException 
(Exception) if error occurs. 

public long streamLength(String sName) throws 35 
DKException, Exception 

Returns the length of the content of the stream specified 
by sName. If the stream does not exist throws DKEx- ^ 
ceptioo. If this is not a (multi)stream object then returns 
content of primary stream (lobData). Note: calls 
getStreamContent(String) for content. 

Parameters: 

45 

sName — name of string to retrieve content's length. 
Returns: 

length of byte array stream content corresponding to 
sName, else length 50 

of content of primary stream. 

Throws: DKException 

is thrown if this is a (multi)stream object and stream does 
not exists 



public boolean isMultiStreamBlob( ) 

Returns true if current content is multistream, false oth- 
erwise. 

public boolean isMultiStreamFlagSet( ) 

Returns true if the object server content is checked for 
Multistream, false otherwise. 

9. Federated Collection 

A federated collection allows an application program to 
process data objects resulting from a query as a group or 
collection and at the same time preserves the sub -grouping 
relationships that exists between them. It provides the user 
with a mechanism: 

to aggregate several collection of data objects while 
preserving each individual collection information 

to treat these collections as one whole unit of collection, 
ignoring 

collection boundaries 

A federated collection is a collection containing DKRe- 
sults objects, it is created to hold the results of 
DKFederatedQuery, which may come from several 
heterogenous datastores. Each DKResults contains the 
results of subquery of the federated query submitted to 
a specific native datastore associated with the federated 
datastore. To iterate over federated collection members 
(which are DKResults objects), a user should create 
and use dklterator or DKSequentiallterator to pull each 
DKResults object. Then he could create another dklt- 
erator on this DKResults to iterate over it and to process 
the result according to its datastore origin. 
Alternatively, the user can create a federated iterator, 
dkFederatedlterator, and use it to iterate over all ele- 
ment members across collection boundaries, regardless 
of which datastore the result came from. In theory, a 
federated collection can contains other nested collec- 
tions up to any arbitrary depth. In the current 
implementation, a federated collection is not queryable. 
See Also: dkFederatedlterator, dklterator, DKSequen- 
tiallterator. 

An example class definition for DKFederatedCollection is 
set forth below. 



DKFederatedCollection 

Class com.ibm.mm.sk.com[non.DKFederatedCollection 
public class DKFederatedCollection 
extends DKSequentialCollection 

{ 

public DKFederatedCoIlection( ) 
public int cardinality^ ) 
public int memberCardinality( ) 
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-continued 



public dkltcratoj creatcIterator( ) 
public dklterator createMemberIterator( ) 

public Object retrieveElementAtfdklterator where) throws DKUsageError 
public void addElement(Object element) throws DKUsageError 
public void addAllElements(dkColIection elements) throws DKUsageError 
public void insert ElementAt(Object element, 

dklterator where) throws DKUsageError 
public void replaceElementAtfObject element, 

dilterator where) throws DKUsageError 
public void removeElementAt(dkIterator where) throws DKUsageError 
public void rcmoveAllElementsC ) 
public void sort( ) throws DKUsageError 
public void sort(boolean order) throws DKUsageError 
public void sort{dkSoit soitFunction, 

boolean sortOrder) throws DKUsageError 



The following methods are part of the DKFederatedCol- 
lection class: 
public DKFederatedCollection( ) 

Default constructor 
public int cardinality( ) 

Returns the number of all individual (leaf) elements 
(non-collection) across the collection boundaries. This 
is the total of all elements in each sub -collections. 
Overrides: 

cardinality in class DKSequentialCollection 
public int memberCardinality( ) 

Returns the number of elements in the collection. The 
element could be a collection object, i.e. DKResults 
object, not necessarily a leaf element (non-collection), 
public dklterator create!terator( ) 

Creates a new dkFederatedlterator for this federated col- 
lection. This iterator can be used to iterate over the 
federated collection, across collection boundaries, 
returning a (non-collection) member one at a time. 

Returns: 

an iterator 

Overrides: 

createiterator in class DKSequentialCollection 
public dklterator createMemberIterator( ) 

Creates a new iterator for this federated collection. The 
new iterator would be supporting DKSequentiallterator 
interface. That is, the method "next" of this iterator 
would return a collection, such as DKResults object. 
User can then, create an iterator on this DKResults to 
iterate over its member. 

Returns: 

an iterator 

public Object retrieveElementAt(dkIterator where) throws 
DKUsageError 

Gets the element that the iterator is pointing at 

Parameters: 

where — location in collection to retrieve an object 

Returns: 

an element 

Overrides: 

retrieveElementAt in class DKSequentialCollection 
public void addElement(Object element) throws DKUsag- 
eError 

Adds an element to the end of the collection, and invali- 
dates all of the current iterators. 



Parameters: 

element — element to be added 
Overrides: . 

addElement in class DKSequentialCollection 
public void addAllElements(dkCollection elements) throws 
DKUsageError 

Adds all elements in the collection, and invalidates all of 
the current iterators. 

Parameters: 

elements — collection of elements to be added 
Overrides: 

addAllElements in class DKSequentialCollection 
public void insertElementAt(Object element, 

dklterator where) throws DKUsageError 

Adds a new element, after the element the iterator is 
currently pointing at. The iterator is advanced to the 
new element, invalidating all other iterators. 

Parameters: 

element — element to be added 
where — location in collection 
Overrides: 

insertElementAt in class DKSequentialCollection 
public void replaceElementAt( Object element, 
dklterator where) throws DKUsageError 
Replaces the element the iterator is currently pointing at. 
Parameters: 

element — element to be added 
iter — location in collection 
Overrides: 

replaceElementAt in class DKSequentialCollection 
public void removeElementAt(dkIterator where) throws 
DKUsageError 

Removes the element the iterator is currently pointing at. 
The iterator is advanced to the next element after this 
operation, invalidating all other iterators. 
Parameters: 

iter — location in collection 
Overrides: 

removeElementAt in class DKSequentialCollection 
public void removeAllElements( ) 

Removes all elements in the collection Invalidates all 

other iterators. 
Overrides: 

removeAllElements in class DKSequentialCollection 
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dkFederatedlterator 

package com. Lbm.mm.sdk. common. dkFederatedlterator 
public interface dkFederatedlterator 
extends DKSequentiallterator * 

{ 

public abstract Object nextf ) throws DKUsageError 
public abstract void reset( ) 
public abstract boolean more( ) 

public abstract Object previous ( ) throws DKUsageError 
public abstract Object at( ) throws DKUsageError 
public abstract boolean setToFirst( ) 
public abstract boolean setTbLast( ) 
public abstract boolean setToNext( ) 
public abstract boolean setToPrevious( ) 
public abstract boolean setToFirstCollection( ) 
public abstract boolean setToLastCollectLon( ) 
public abstract boolean sefIoNextCo]lection( ) 
public abstract boolean setToPreviousCoLlection( ) 



} 



10 



public void sort( ) throws DKUsageError 
Sort is not supported in the FederatedColLection. Excep- 
tion will be thrown if this function is called. 
Overrides: 

sort in class DKSequentialCollection 
public void sort(boolean order) throws DKUsageError 
Sort is not supported in the FederatedCollection. Excep- 
tion will be thrown if this function is called. 
Overrides: 

sort in class DKSequentialCollection 
public void sort(dksort sortFunction, 

boolean sortOrder) throws DKUsageError 
Sort is not supported in the FederatedCollection. Excep- 
tion will be thrown if this function is called. 15 
Overrides: 

sort in class DKSequentialCollection 

A federated iterator is used to iterate over the collective 
members of DKFederatedCollection across collection 
boundaries. The next( ) method returns DDO objects 20 
until all collections are iterated over. This iterator is 
created by invoking the method createIterator( ) in the 
DKFederatedCollection object. See Also: dklterator, 
DKSequentiallterator 

An example class definition for dkFederatedlterator is set 25 
forth below. 
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The following methods are part of the dkFederatedlterator 
class: 

public abstract Object next( ) throws DKUsageError 5Q 

Returns the current element in the collection and advances 
the iterator to the next position. In case the element is 
a collection, it goes inside that collection and retrieves 
the first element recursively, until it finds an element 
which is not a collection. When the current collection 
is exhausted, this iterator will find the next collection 
and extract the first element (non-collection) from it. 

Throws: DKUsageError 

if already at the last item in collection 
public abstract void reset( ) 60 

Resets the iterator to the beginning of DKFederatedCol- 
lection. 

public abstract boolean more( ) 

Returns true if there are more elements in the DKFeder- 
atedCollection. In this case, an element implicitly 65 
means a collection member which is not a collection (a 
leaf). 



public abstract Object previous( ) throws DKUsageError 
Returns the current element in the collection and moves 
the iterator backward one position. In case the element 
is a collection, it goes inside that collection and 
retrieves the last element, until it finds an element 
which is not a collection. When the current collection 
is exhausted, this iterator will find the previous collec- 
tion and extract the last element (non-collection) from 
it. 

Throws: DKUsageError 

if already at the first item in collection 
public abstract Object at( ) throws DKUsageError 

Returns the current element in the collection without 
moving the iterator position. The returned element is 
not a collection. Throws: DKUsage if collection is 
empty, or current position is invalid, 
public abstract boolean setToFirst( ) 

Sets the iterator to the first element in this federated 
collection. The first element is not a collection. Returns 
true if the operation is successful, otherwise it returns 
false. 

public abstract boolean setToLast( ) 

Sets the iterator to the last element in this federated 
collection. The last element is not a collection. Returns 
true if the operation is successful, otherwise it returns 
false. 

public abstract boolean setToNext( ) 

Sets the iterator to the next element in this federated 
collection. The next element is not a collection. Returns 
true if the operation is successful, otherwise it returns 
false. 

public abstract boolean setToPrevious( ) 

Set the iterator to the previous element in this federated 

collection. The previous element is not a collection. 

Returns true if the operation is successful, otherwise it 

returns false, 
public abstract boolean setToFirstCollection( ) 

Sets the iterator to the first element in the first collection 

in this federated collection. The first element is not a 

collection. Returns true if the operation is successful, 

otherwise it returns false, 
public abstract boolean setToLastCollection( ) 

Sets the iterator to the last element in the last collection in 

this federated collection. The last element is not a 

collection. Returns true if the operation is successful, 

otherwise it returns false, 
public abstract boolean setToNextCollection( ) 

Sets the iterator to the first element in the next collection 
in this federated collection. The first element is not a 
collection. Returns true if the operation is successful, oth- 
erwise it returns false. 

public abstract boolean setToPreviousCollection( ) 

Sets the iterator to the last element in the previous 
collection in this federated collection. The first last is 
not a collection. Returns true if the operation is 
successful, otherwise it returns false. 
10. Sequential Collection 
DKSequentialCollection is a subclass of dkCollection 
which supports sorting and sequential access in a 
bi-directional manner, i.e. forward and backward. A 
sequential collection is not queryable. DKSequential- 
Collection can create and support 
DKSequentiallterator, which is also bi-directional. 
An example class definition for DKSequentialCollection 
is set forth below. 
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DKScquentialCollectio n 

package com. ibm.mm.sdk.common.DKSequeatial Collection 
public class DKSequentialCollection 
extends Object 

implements dkCollection, DKMcssageld, Serial izable 

public DKSequentialCollection( ) 

public DKSequentialCollection(dkSort sortFunction) 

public int cardinality^ ) 

public dklterator creatc[terator( ) 

public Object retrieveElementAt(dkIteiator iter) throws DKUsageError 
public void addElement(Object element) throws DKUsageError 
public void insertElementAt(Object element, 

dklterator iter) throws DKUsageError 
public void replaceEIemtntAt(Object element, 

dklterator iter) throws DKUsageError 
public void removeEtementAt(dklterator iter) throws DKUsageError 
public void rcmoveAllElements( ) throws DKUsageError 
public void setName (String name) 
public String getName( ) 
public void setSortFunction(dkSort sortFtmction) 
public dkSort getSortFunction( ) 
public void sort( ) throws DKUsageError 
public void sort(boolean order) throws DKUsageError 
public void sort(dkSort sortFunction, 

boolean sortOrder) throws DKUsageError 

} 



The following methods are part of the DKSequentialCol- 
lection class: 

public DKSequentialCollection( ) 

Constructs a DKSequentialCollection. 
public DKSequentialCollection(dkSort sortFunction) 
Constructs a DKSequentialCollection with the given sort 
function. 

Parameters: 

sortFounction — sort function, 
public int cardinality( ) 

Gets the number of elements in the collection. 
Returns: 

the number of elements, 
public dklterator createlterator( ) 

Creates a new iterator for this collection. The default is 

DKSequentiallterator object. 
Returns: 
an iterator 

public Object retrieveElementAt(dkIterator iter) throws 
DKUsageError 

Gets the element that the iterator is pointing at. 

Parameters: 

iter — location in collection to retrieve an object. 

Returns: 

an element 

public void addElernent(Object element) throws DKUsag- 
eError 

Adds an element to the end of the collection, and invali- 
dates all of the current iterators. 
Parameters: 

element — element to be added, 
public void insertElementAt(Object element, 

dklterator iter) throws DKUsageError 

Adds a new element, after the element the iterator is 
currently pointing at. The iterator is advanced to the 
new element, invalidating all other iterators. 



Parameters: 

element — element to be added, 
iter — location in collection, 
public void replaceElementAt(Object element, 

dklterator iter) throws DKUsageError 

Replaces the element the iterator is currently pointing at. 

Parameters: 

element — element to be added, 
iter — location in collection, 
public void removeElementAt(dkIterator iter) throws 
DKUsageError 
Removes the element the iterator is currently pointing at. 
The iterator is advanced to the next element after this 
operation, invalidating all other iterators. 
Parameters: 

iter — location in collection 
public void removeAllElements( ) throws DKUsageError 

Removes all elements in the collection and invalidates all 
other iterators, 
public void setName(String name) 

Sets the name of the collection. 

Parameters: 

name — collection name, 
public String getName( ) 

Gets the name of the collection. 

Returns: 

collection name 
public void setSortFunction(dkSort sortFunction) 

Sets the sort function for sorting this collection. 

Parameters: 

sortFunction — the sort function, 
public dkSort getSortFunction( ) 
Gets the sort function. 
Returns: 

a sort function object, 
public void sort( ) throws DKUsageError 
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Sorts the elements in this collection using the sort func- 
tion. The default order is ascending. The sort function 
must be set before. 

See Also: 

sort 

public void sort(boolean order) throws DKUsageError 
Sorts the elements in this collection in the given order 
using the sort function. The sort function must be set 
before. 

Parameters: 

order — a boolean value indicating the sort order. If true 
sort in ascending order, otherwise sort in descending 
order. 

See Also: 

sort 

public void sort(dkSort sortFunction, 

boolean sortOrder) throws DKUsageError 
Sorts the elements in this collection using the given sort 
function and sort order. sortFunction is a function 
object which defines the method to get the object key 
and perform comparison on them. 
Parameters: 

sortFunction — the sort function. 

sortOrder — a boolean value indicating the sort order. If 
true sort in 

ascending order, otherwise sort in descending order. 
11. Folders, Parts, and Persistent Identifiers 

DKFolder is a subclass of sequential collection. Its pur- 
pose is to hold a collection of document DDO and 
folder DDO, members of a folder DDO. The DDO 
representing a folder has an attribute with reserved 
name of DKFolder, its value is a reference to the 
DKFolder collection. DKFolder inherits the public 
interface of sequential collection, but internally it keeps 
track of member addition and deletion (to be reflected 
when the DDO is saved to the back-end datastore). In 
addition to the inherited methods, DKFolder has two 
additional methods: addMember( ) and 
removeMember( ). 

An example class definition for DKFolder is set forth 
below. 
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public void addMembcr(DKDDO folder, 

DKDDO member) throws DKException 
public void removeMember(DKDDO folder, 

DKDDO member) throws DKException 



} 



package com. ibm.mm.sdk. common. DKFolder 
public class DKFolder 

extends DKSequentialCollection 

implements DKOonstant, DKMessageld, Serializable 



The following methods are part of the DKFolder class: 
public void addMember(DKDDOfolder, 

DKDDO member) throws DKException 
Adds a new member to this folder and reflects the results 
immediately in the datastore, i.e. make it persistent. At 
the end of the operation, the new member will be in this 
DKFolder collection in-memory, as well as in the 
persistent folder representation in the datastore. In 
Digital Library, the member must exists (has been 
created) in the datastore before it can be added to a 
folder. 

Parameters: 
folder — a folder object 

member — the member to be added to the folder 
public void removeMember(DKDDOfolder, 

DKDDO member) throws DKException 
Removes a member from this folder and reflects the 
results immediately in the datastore, i.e. make it per- 
sistent. At the end of the operation, the member object 
will not be in this DKFolder collection in-memory, and 
it will also be removed from the persistent folder 
representation in the datastore. 

Parameters: 

folder — a folder object 

member — the member to be removed from the folder 
DKParts is a subclass of a sequential collection. Its 
purpose is to hold part XDO members of a document object. 
The DDO representing a document has an attribute with 
reserved name of DKParts, its value is a reference to the 
45 DKParts collection. DKParts inherits the public interface of 
sequential collection, but internally it keeps track of member 
addition and deletion (to be reflected when the DDO is saved 
to the back-end datastore). In addition to the inherited 
methods, DKParts has two additional methods: 
addMember( ) and removeMember( ). 

An example class definition for DKParts is set forth 
below. 



50 



DKParts 

package com.ibm.mm.sdlccommon.DKParts 
public class DKParts 

extends DKSequentialColtection 

implements DKCoostant, Serializable 

{ 

public DKPartsf ) 

public dkColtection getAffiliatediypesfint afiHiatediype) throws DKException, Exception 
public void addMember (DKDDO item, 

dkXDO member) throws DKException, Exception 
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The following methods are part of the DKParts class: 
public DKParts( ) 

Constructs a DKParts object, 
public dkcollection getA3iliatedTypes(int affiliatedType) 
throws DKException, Exception 

Gets the specified affiliated type objects from this part 
collection. Examples of affiliated types are DK_CM_ 
ANNOTATION, DK_CM__NOTE, etc. 
Parameters: 

affiliatedType — the desired affiliated type to extract. 
Returns: 

a collection of xdo objects having the specified affiliated 
types 

public void addMember(DKDDO item, 

dkXDO member) throws DKException, Exception 
Adds a new member into this parts collection and reflects 
the results immediately in the datastore, i.e. make it 
persistent. The new member must not exists in the 
persistent store. At the end of the operation, the new 
member will be in this DKParts collection in-memory, 
as well as in the persistent item representation in the 
datastore. This operation has the same effect as the 
sequencing of member.add( ) and this.addElement 
(member), where member is the part XDO and this is 
the collection of parts (DKParts) in this item. 
Parameters: 

item — the data object that contains this parts collection 
member — the member to be added to this parts collection 
public void removeMember(DKDDO item, 

dkXDO member) throws DKException, Exception 
Removes a member from this parts collection and reflects 
the results immediately in the datastore, i.e. make it persis- 
tent. At the end of the operation, the member object will not 
be in this DKParts collection in-memory, and it will also be 
removed from the persistent item representation in the 
datastore. This operation has the same effect as the sequenc- 
ing of this.removeElement(member) and member.del( ), 
where member is the part XDO and this is the collection of 
parts (DKParts) in this item. 
Parameters: 

item — the data object that contains this parts collection 
member — the member to be removed from this parts 
collection 

The DKPid class represents a Pid (Persistent identifier) 
object. An example class definition for DKPid is set 
forth below. 



DKPid 



package co in. ibm .mm . sdk co m mon. DKPid 
public class DKPid 
extends Object 

implements DKMessagcId, Serializable 

{ 

public DKPidf ) 
public DKPid(int fdStringCount) 

public DKPid(String sourcePidString) throws DKException 
public DKPidfDKPid pid) 
public String getDatastoreType( ) 

public void setDatastoreiype(String sourceDatastoreType) 
public String getDatastorcName( ) 

public void setDatastoreName(String sourceDatastoreName) 

public String gttldf ) 

public void set!d(String sourceld) 



25 
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-continued 



public String gctIdString( ) 

public void setIdString(String sourceld) 
5 public String getPrimary[d( ) 

public void setPrimaryId(String primaryld) 

public String pidString( ) 

public String getObjectTypef ) 

public void setObjectType(String sourceObjectType) 

public boolean isSet( ) 
10 public int getLdStringCount( ) 

public void setIdStringCount(int idStringCount) 

public String getIdString(int index) throws DKException 

public void setIdString(int index,' 

String idStringltem) throws DKException 

public boolean equals (Object otherObject) 
25 public Object clone ( ) 

public String pidiype( ) 

} 



The following methods are part of the DKPid class: 
public DKPid( ) 

Constructs a Pid object, 
public DKPid(int idStringCount) 
Constructs a Pid object 
Parameters: 

idStringCount — string id count 
public DKPid(String sourcePidString) throws DKException 
Constructs a Pid object from a Pid string representation. 
Parameters: 

sourcePidString — the Pid string, a string obtained by 
calling the 

pidstring( ) method in Pid. 
public DKPid(DKPidpid) 

Constucts a Pid from another Pid. 

Parameters: 

pid — the other Pid 
public String getDatastoreType( ) 

Gets the datastore type from this Pid. 

Returns: 

the datastore type, 
public void setDatastoreiype(String sourceDatastoreType) 
Sets the datastore type of this Pid. 
Parameters: 

sourceDatastoreType — datastore type, 
public String getDatastoreName( ) 
Gets the datastore name from this Pid. 
Returns: 

the datastore name 
public void setDatastoreName(String 
sourceDatastoreName) 

Sets the datastore name of this Pid. 

Parameters: 

sourceDatastoreName — datastore name 
public String getld( ) 

Gets the datastore specific persistent-id of the owner 
data-object. This id contains information to locate the 
persistent data, of the owner data-object, in the datas- 
tore. Note: getld( ) is deprecated. Replace by getPri- 
maryld. 

Returns: 

the datastore persistent-id 
See Also: 
getPrimaryld 
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public void setId(String sourceld) 

Sets the datastore specific persistent-id for the owner 
data-object. Note: setid( ) is deprecated. Replace by 
setprimaryld. 

Parameters: 

sourceld — datastore persistent-id 

See Also: 

setPrimaryld 
public String getIdString( ) 

Gets the datastore specific persistent-id of the owner 
data-object This id contains information to locate the 
persistent data, of the owner data-object, in the datas- 
tore. 

Returns: 

the datastore persistent-id. 
public void setIdString(String sourceld) 

Sets the datastore specific persistent-id for the owner 
data-object. The user should also set the item id when- 
ever the id string is set. 

Parameters: 

sourceld — datastore persistent-id 
public String getPrimaryId( ) 

Gets the datastore specific primary persistent-id 
Returns: 

the datastore primary persistent-id 
public void setPrimaryId(StriQg primaryld) 
Sets the datastore specific primary persistent-id 
Parameters: 

primaryld — datastore primary persistent-id 
public String pidString( ) 

Gets the string representation of the Pid, This string is of 
internal format and not to be parsed by users. This 
string can be used as an input parameter to re-construct 
the Pid using the proper constructor. 

Returns: 

string representation of the Pid. 

See Also: 

DKPid 

public String getObjectType( ) 

Gets the type of the data-object owning this Pid. 

Returns: 

the object type 
public void setObjectType(String sourceObjectType) 

Sets the type of thejdata -object owning this Pid. 

Parameters: 

toObjectType — the object type 
public boolean isSet( ) 

Returns true if all components of this Pid are set to their 
intended values. 

Returns: 

true or false, 
public int getIdStringCount( ) 

Gets id string count 

Returns: 

the id string count 
public void setIdStringCount(int idStringCount) 
Sets id string count 
Parameters: 

idStringCount — the id string count 
public String getIdString(int index) throws DKException 
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Gets id string by index (0 to n-1) 
Parameters: 

index — the index of a part of the id string 
Returns: 

a part of the id string by index 
public void setIdString(int index, 

String idStringltem) throws DKException 
Sets id string by index (0 to n-1) 
Parameters: 

index — the index of a part of the id string 
idStringltem — a part of the id string 
public boolean equals(Object otherObject) 

Compares this Pid if it is equal to another Pid. All 

data-members are compared for equality. 
Parameters: 

otherObject — the other Pid. 
Returns: 

s true if this Pid equals to otherobject. 
Overrides: 

equals in class object 
public Object clone( ) 
Clones. 
Returns: 

the a copy of Pid 
Overrides: 

clone in class object 
public String pidType( ) 
Gets Pid type. 
Returns: 
the pid type. 

The DKPidXDODL class represents a Pid (Persistent 
identifier) object for an extended data object in a 
Digital Library. An example class definition for 
DKPidXDODL is set forth below. 
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DKPidXDODL 



45 
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package com.ibm.mm.sdkcommoa.DKPidXDODL 
public class DKPidXDODL 
extends DKPidXDO 

implements DKConstant, DKMessageld, Serializable 
public DKPidXDODL( ) 

public DKPidXDODL(String aPidString) throws DKException 

public DKPidXDODL(DKPidXDODL aDKPidXDODL) 

public String getld( ) 

public void setld (String sourceld) 

public String gctPrimarytdf ) 

public void setPrimaryId(String primaryld) 

public int getPart!d( ) 

public void setPartId(int aPartld) 

public String getltemld( ) 

public void setltemld (String altemld) 

public boolean isSet( ) 

public Object clonef ) 

public boolean equals (Object otherObject) 

public String getRepType( ) 

public void setRcpType(String aRType) 

public String pidType( ) 



The following methods are part of the DKPidXDODL 
65 class: 

public DKPidXDODL( ) 
Constructs a Pid 
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public DKPidXDODL(String aPidStriog) throws DKExcep- 
tion 

Constructs a Pid 
Parameters: 
aPidString — pid string 
public DKPidXDODL(DKPidXDODL aDKPidXDODL) 
Constructs a Pid 
Parameters: 

aDKPidXDODL — XDO pid for DL 
public String getld( ) 

Gets the datastore specific persistent-id of the owner 
data-object. This id contains information to locate the 
persistent data, of the owner data-object, in the datas- 
tore. Note: getJd( ) is deprecated. Replace by getPri- 
maryld. 

Returns: 

the datastore persistent-id. 
Overrides: 

getld in class DKPid 
See Also: 
getPrimaryld 
public void setId(String sourceld) 

Sets the datastore specific persistent-id for the owner 

data-object Note: setld( ) is deprecated. Replace by 

setPrimaryld. 
Parameters: 

sourceld — datastore persistent-id 
Overrides: 

setld in class DKPid 
See Also: 
setPrimaryld 
public String getPrimaryId( ) 

Gets the datastore specific Primary persistent-id 
Returns: 

the datastore Primary persistent-id 
Overrides: 

getPrimaryld in class DKPid 
public void setPrimaryId(String primaryld) 

Sets the datastore specific Primary persistent-id 
Parameters: 

primaryld — datastore primary persistent-id 
Overrides: . 

setPrimaryld in class DKPid 
public int getPartId( ) 

Gets the Part id 

Returns: 

the part id 
public void setPartId(int aPartld) 

Sets the Part id 

Parameters: 

aPartld — the part id 
public String getltemdl( ) 

Gets the Item id 

Returns: . . 

the item id 
public void setItemId(String altemld) 
Sets the Item id 
Parameters: 
altemld — the item id 
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public boolean isSet( ) 
Pid values set indicator 
Returns: 

true is all components of this Pid are set to their intended 
values. 

Overrides: 

isSet in class DKPidXDO 
public Object clone( ) 
Clones 
Returns: 

the a copy of Pid 
Overrides: 

clone in class DKPidXDO 
public boolean equals(Object otherObject) 
Compares Pids 
Returns: 
20 true if to pids are equal 
Overrides: 

equals in class DKPid 
public String getRepType( ) 
25 Gets the representation type of the part 
Returns: 

the representation type 
public void setRepType(String aRType) 
30 Sets the representation type of the part 
Parameters: 

aRType — a representation type 
public String pidType( ) 
Gets Pid type. 
Returns: 
the pid type. 
Overrides: 

pidType in class DKPidXDO 
12. Result Sets 

DKResults is a sub-class of dkQueryableCollection, 
therefore it supports sorting and bi-directional iterator, 
and it is queryable, Element members of DKResults are 
45 always DKDDO objects, which represent hits from a 
query. The iterator created by this class is DKSequen- 
tiallterator. An example class definition for DKResults 
is set forth below. 



DKResults 
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package com. ibm.mm.sdk. common. DKResults 
public class DKResults 

extends dkQueryableCollection 

implements DKMessageld, DKConstant, Serializable 

public DKResults(dkDatastore ds) 
public Object cvaluate(String query, 



The following methods are part of the DKResults class: 
public DKResults(dkDatastore ds) 

Constructs a DKResults with a given datastore object. 
Parameters: 

ds — the associated datastore object where the results 
come from. 
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public Object evaluate(String query, 
short QLType, 

DKNVPair params[ ]) throws DKUsageError, 
DKException, Exception 



122 

13. Result Set Cursor 

dkResultSetCursor is used for a result of a set of cursors 
pointing to data in one or more datastores. An example 
class definition for dkResultSetCursor is set forth 
below. 



dkResultSetCursor 

package co m. ibm .mm.sdkxommo a. ResultSetCursor 

public interface dkResultSetCursor 

{ 

public abstract boolean isscrollable() throws DKException, Exception 
public abstract boolean isUpdatableO throws DKException, Exception 
public abstract boolean isValidQ throws DKException, Exception 
public abstract boolean isOpenQ throws DKException, Exception 
public abstract boolean isBeginO throws DKException, Exception 
public abstract boolean isEnd() throws DKException, Exception 
public abstract boolean isInBetweenO throws DKException, Exception 
public abstract int getPositionO throws DKException, Exception 
public abstract void eetPosiUonfint position, 

Object value) throws DKException, Exception 
public abstract void setToNext() throws DKException, Exception 
public abstract DKDDO fetchObjecuQ throwB DKException, Exception 
public abstract DKDDO fetchNext() throws DKException, Exception 
public abstract boolean fetchNextN(int how_many, 

dkCollection collection) throws DKException, Exception 
public abstract Object fetchObjectByName(String dataltemName) throws DKException, 
Exception 

public abstract Object fetchNextByNarne(String datattcmName) throws DKException, 
Exception 

public abstract boolean fetchNextNByName(String dataltemName, 
int how__many, 

Object anayfj throws DKException, Exception 
public abstract DKDDO flndObject(int position, 

String predicate) throws DKException, Exception 
public abstract void deleteObjecuQ throws DKException, Exception 
public abstract void updateObject(DKDDO ddo) throws DKException, Exception 
public abstract DKDDO newObject() throws DKException, Exception 
public abstract void addObject(DKDDO ddo) throws DKException, Exception 
public abstract void open() throws DKException, Exception 
public abstract void closeQ throws DKException, Exception 
public abstract void destroyO throws DKException, Exception 
public abstract void open(DKNVPair panns[]) throws DKException, Exception 
public abstract String datastoreNameO throws Exception 
public abstract String datastoreTypeQ throws Exception 
public abstract DKHandle handle(int type) throws Exception 
public abstract DKHandle handle(String type) throws Exception 
public abstract int cardinality Q throws DKException, Exception 
public abstract String objectTypcO throws Exception 



45 

Evaluates the given query using the current element 
members of this collection as the scope of the query. 
The new results is an intersection between the results of 
the new query with the current element members of this 50 
collection. This method implements the queryable 
behavior of dkQueryableCollection. 

Side -effects: 

this collection members will be sorted by itemid. 55 

all iterators will be invalidated. 

Parameters: 

query — the new query string to be evaluated. 

QUtype — the query language type of the new query. 60 

params — the parameter array required to evaluate the 

query. 
Returns: 

a new DKResults object containing the intersection. 
Overrides: 

evaluate in class dkQueryableCollection 



The following methods are part of the dkResultSetCursor 
class: 

public abstract boolean isScrollabie( ) throws DKException, 
Exception 

Scrollable indicator 

Returns: 

true if cursor can be scrolled forward and backward, 
public abstract boolean isUpdatable( ) throws DKException, 
Exception 

Updatable indicator 

Returns: 

true if cursor is updatable. 
public abstract boolean isValid( ) throws DKException, 
Exception 

Valid indicator 

Returns: 

true if cursor is valid, 
public abstract boolean isOpen( ) throws DKException, 
Exception 

Open indicator 
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Returns: Returns: 

true is cursor is in an opened state. object 

public abstract boolean isBegin( ) throws DKException, public abstract Object fetchNextByName(String 

Exception dataltemName) throws DKException, Exception 

Begin indicator 5 Sets cursor to point to the position of the next data object 

Returns: an d fetches the data item value in the cursor at that 

true if cursor is positioned at the beginning. V osiiion b y data item name ' 

public abstract boolean isEnd( ) throws DKException, Parameters: 

Exception 10 dataltemName — data item name 

End indicator Returns: 

Returns: object 

true if cursor is positioned at the end. public abstract boolean fetchNextNByName(String 

public abstract boolean isInBetween( ) throws dataltemName, 

DKException, Exception 15 int how_many, 

Between data objects in cursor indicator Object array[ ]) throws DKException, Exception 

Returns: Fetches the next N data item values of the cursor and 

true if cursor is in between data objects in the cursor. inserts them into the given array 

public abstract int getPosition( ) throws DKException, 20 Parameters: 

Exception dataltemName — data item name 

Gets the current cursor position how_many— how many data item values the user wants 

Returns: to be returned in the collection. 

cursor position ^ array — the array where the data item values that are 

public abstract void setPosition(int position, fetched are stored. 

Object value) throws DKException, Exception Returns: 

Sets the cursor position true if there is at least one data item value returned. 

Parameters: public abstract DKDDO findObject(int position, 

position— cursor position option 30 Strin S predicate) throws DKException, Exception 

value^cursor position value Find ±c data ob i ect which satisfies lhe & iven predicate, 

public abstract void setToNext( ) throws DKException, move the cursor t0 P° sltlon > fetch - 

Exception Returns: 

Sets cursor to point to the position of the next data object 35 DDO 

in the cursor. public abstract void deleteObject( ) throws DKException, 

public abstract DKDDO fetchObject( ) throws Exception 

DKException, Exception Deletes element at the current cursor position from the 

Fetches the element in the cursor at the current position Datastore 

Returns* 40 pub ^ c abstracl void updateObject(DKDDO ddo) throws 



DDO 



DKException, Exception 



ui- u * * rwT^r* * . uxt u \ nirr Updates element at the current cursor position from the 

public abstract DKDDO fetchNext( ) throws DKException, Datastore 

Exception public abstract DKDDO newObject() throws DKException, 

Sets cursor to point to the position of the next data object 45 Exception 

and fetches the element in the cursor at that position. Constructs a new DDO of the same type as the items in 

Returns: tne resu i t 

DDO Returns: 

public abstract boolean fetchNextN(int how_many, DDO 

dkCollection collection) throws DKException, Exception 50 public abstract void addObject(DKDDO ddo) throws 

Fetches the next N elements of the cursor and inserts them DKException, Exception 

into the given collection. Adds an element to the Datastore 

Parameters : public abstract void open( ) throws DKException, Exception 

how_many — how many elements the user wants to be 55 Opens the cursor. This reexcutes the query and repositions 

returned in the collection. the cursor to the beginning, 

collection— the collection where elements that are fetched P ubUc abstract void close < > ihtam DKException, Excep- 

are stored. Uon 

Returns' Close the cursor and invalidates the result set. 

., ' t , fin public abstract void destroy( ) throws DKException, Excep- 

true if there is at least one data object returned. ou ^ Qn r 

public abstract Object fetchObjectByName(String ~ ~. . „ r 

dataltemName) throws DKException Exception De K Str f oys ^ cursor T^is method allows for cleanup, 

_ , , ' . ' , before garbage-collection is done on this class. 

Fetches the data item value in the cursor at the current public abstract void ope n(DKNVPair parms[ ]) throws 

position by data item name. fi5 DKException, Exception 

Parameters: Opens the cursor. This reexecutes the query and reposi- 

dataltemName — data item name tions the cursor to the beginning. 
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Gets a cursor handle 
Parameters: 

type — type of cursor handle wanted 
Returns: 
a cursor handle 



Parameters: 

parms — allows for parameters to be passed in for the 
reexecution of the query, 
public abstract String datastoreName( ) throws Exception 

Gets the datastore name 5 

Returns: 

datastore name 
public abstract String datastoreType( ) throws Exception 

Gets the datastore type io 

Returns: 

datastore type 

public abstract DKHandle handle(int type) throws Excep- 
tion 

Gets a cursor handle. Note: handle( ) is deprecated. 15 P ublic abstract String objectType( ) throws Exception 

Replace by handle(String type). 
Parameters: 

type — type of cursor handle wanted 
Returns: 20 
a cursor handle 
See Also: 
handle 

public abstract DKHandle handle(String type) throws 
Exception 



public abstract int cardinality^ ) throws DKException, 
Exception 

Gets the number of query results 
Returns: 

number of query results 



Gets the cursor object type 
Returns: 

cursor object type 

14. Federated Result Set Cursor 

DKResultSetCursorFed is a result set cursor for a feder- 
ated datastore. An example class definition for DKResult- 
SetCursorFed is set forth below. 



DKResultSetCursorFed 

co m. ibm.mm. sdk.server.DKResultSetCursorFed 
public class DKResultSetCursorFed 

extends dkAbstractResultSetCursor 

implements DKConstantFed, DKMessageldFed 

public DKRc5uitSetCursorFed(DKDatastoreFed ds, 

DKNVPair parms[]) throws DKException, Exception 

public boolean isScrollableO throws DKException, Exception 

public boolean is UpdatableO throws DKException, Exception 

public boolean isvalidO throws DKException, Exception 

public boolean isOpenO throws DKException, Exception 

public boolean isBegLn0 throws DKException, Exception 

public boolean isEnd() throws DKException, Exception 

public boolean isInBetweenO throws DKException, Exception 

public int getPosition0 throws DKException, Exception 

public void setPosition(int position, 

Object value) throws DKException, Exception 

public void setToNextO throws DKException, Exception 

public DKDDO fctchObjcctf) throws DKException, Exception 

public DKDDO fetchNext() throws DKException, Exception 

public boolean fetchNextN(int how_many, 

dkCo I lection collection) throws DKException, Exception 

public Object fetchObjectByName(String dataltemName) throws DKException, Exception 

public Object fetchNcxtByNamefString dataltemName) throws DKException, Exception 

public boolean fetchNextNByName(String dataltemName, 
int how__many, 

Object array! I) throws DKException, Exception 
public DKDDO findObject(int position, 

String predicate) throws DKException, Exception 
public void deleleObjectO throws DKException, Exception 
public void updateObject(DKDDO ddo) throws DKException, Exception 
public DKDDO newObjecuQ throws DKException, Exception 
public void addObject(DKDDO ddo) throws DKException, Exception 
public void open() throws DKException, Exception 
public void closeQ throws DKException, Exception 
public void destroyO throws DKException, Exception 
public void op en (DKNVPair parms[]) throws DKException, Exception 
public String datastoreNamcO throws Exception 
public String datastoreTypeO throws Exception 
public DKHandle handle(int type) throws Exception 
public DKHandle handle(Stiing type) throws Exception 
public int' cardinality 0 throws Exception 
public void done() 

public synchronized void addRSCursor(ResultSetCursor rsCursor) 
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-continued 

public synchronized dkRcsultSetCursor fetchNcxtCursorO throws DKException, 

Exception 

} 



The following methods are part of the DKResultSetCur- 
sorFed class: 

public DKResultSetCursorFed(DKDatastoreFed ds, 

DKNVPair parms[ ]) throws DKException, Exception 
public boolean isScrollable( ) throws DKException, Excep- 
tion 

Overrides: 

isScrollable in class dkAbstractResultSetCursor 
public boolean isUpdatable( ) throws DKException, Excep- 
tion 

Overrides: 

isUpdatable in class dkAbstractResultSetCursor 
public boolean isValid( ) throws DKException, Exception 
Overrides: 

isValid in class dkAbstractResultSetCursor 
public boolean isOpen( ) throws DKException, Exception 
Overrides: 

isOpen in class dkAbstractResultSetCursor 
public boolean isBegin( ) throws DKException, Exception 
Overrides: 

isBegin in class dkAbstractResultSetCursor 
public boolean isEnd( ) throws DKException, Exception 
Overrides: 

isEnd in class dkAbstractResultSetCursor 
public boolean isInBetween( ) throws DKException, Excep- 
tion 

Overrides: 

islnBetween in class dkAbstractResultSetCursor 
public int getPosition( ) throws DKException, Exception 
Overrides: 

getPosition in class dkAbstractResultSetCursor 
public void setPosition(int position, 

Object value) throws DKException, Exception 
Overrides: 

setPosition in class dkAbstractResultSetCursor 
public void setToNext( ) throws DKException, Exception 
Overrides: 

setToNext in class dkAbstractResultSetCursor 
public DKDDO fetchObject( ) throws DKException, Excep- 
tion 

Overrides: 

fetchObject in class dkAbstractResultSetCursor 
public DKDDO fetchNext( ) throws DKException, Excep- 
tion 

Overrides: 

fetchNext io class dkAbstractResultSetCursor 
public boolean fetchNextN(int how_oiany, 

dkCollection collection) throws DKException, Exception 
Overrides: 

fetchNextN in class dkAbstractResultSetCursor 
public Object fetchObjectByName(String dataltemName) 
throws DKException, Exception 

Overrides: 

fetchObjectByName in class dkAbstractResultSetCursor 



10 



25 



public Object fetchNextByName(String dataltemName) 
throws DKException, Exception 
Overrides: 

fetchNextByName in class dkAbstractResultSetCursor 
public boolean fetchNextNByName(String dataltemName, 
int how__many, 
15 Object arrajf ]) throws DKException, Exception 
Overrides: 

fetchNextNByName in class dkAbstractResultSetCursor 
public DKDDO findObject(int position, 
20 String predicate) throws DKException, Exception 
Overrides: 

findObject in class dkAbstractResultSetCursor 
public void deleteObject( ) throws DKException, Exception 
Overrides: 

deleteObject in class dkAbstractResultSetCursor 
public void updateObject(DKDDO ddo) throws 
DKException, Exception 
Overrides: 

30 updateObject in class dkAbstractResultSetCursor 

public DKDDO newObject( ) throws DKException, Excep- 
tion 
Overrides: 

_ newObject in class dkAbstractResultSetCursor 
public void aadObject(DKDDO ddo) throws DKException, 
Exception 
Overrides: 

addObject in class dkAbstractResultSetCursor 
40 public void open( ) throws DKException, Exception 
Overrides: 

open in class dkAbstractResultSetCursor 
public void close( ) throws DKException, Exception 
Overrides: 

close in class dkAbstractResultSetCursor 
public void destroy( ) throws DKException, Exception 
Overrides: 

destroy in class dkAbstracesultSetCursor 
50 public void open(DKNVPair parms[ ]) throws 
DKException, Exception 
Overrides: 

open in class dkAbstractResultSetCursor 
public String datastoreName( ) throws Exception 
Overrides: 

datastoreName in class dkAbstractResultSetCursor 
public String datastoreType( ) throws Exception 
Overrides: 

60 datastoreType in class dkAbstractResultSetCursor 
public DKHandle handle(int type) throws Exception . 
Overrides: 

handle in class dkAbstractResultSetCursor 
65 public DKHandle handle(String type) throws Exception 
Overrides: 

handle in class dkAbstractResultSetCursor 
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public int cardinality( ) throws Exception 
Overrides: 

cardinality in class dkAbstractResultSetCursor 
public void done( ) 

public synchronized void addRSCursor(dkResultSetCursor 
rsCursor) 

public synchronized dkResultSe tCursor 
fetchNextRSCursor( ) throws DKException, Exception 
15. Queries 

dkQuery is a base class for other query classes. An 
example class definition for dkQuery is set forth below. 
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tion of one parametric, one text, and one image query. 
An example class definition for DKCQExpr is set forth 
below. 



DKCQExpr 



package com.ibm.mm.sdk,common.DKCQExpr 
public class DKCQExpr extends Object 
implements Serializable 



dkQuery 

package com.ibm.mm.sdkrommoiL dkQuery 
public interface dkQuery 
extends dkQueryBase 

{ 

public abstract short qlTypeQ 
public abstract String queryStringO 
public abstract dkDatastoTe datastore() 
public abstract dkDatastore getDatastoreQ 

public abstract void setDatastore(dkDatastore ds) throws DKException, Exception 

public abstract String getNameQ 

public abstract void setName(String name) 

} 



The following methods are part of the dkQuery class: 
public abstract short qlType( ) 

Gets the query type. 

Returns: 

the query type 
public abstract String queryString( ) 

Gets the query string. 

Returns: 

the query string 
public abstract dkDatastore datastore( ) 

Gets the reference to the owner datastore object. Note: 

datastore( ) is deprecated. Replace by getdatastore. 
Returns: 

the dkDatastore object 
See Also: 
getDatastore 
public abstract dkdatastore getDatastore( ) 

Gets the reference to the owner datastore object. 
Returns: 

the dkDatastore object 
public abstract void setDatastore(dkDatastore ds) throws 
DKException, Exception 

Sets the reference to the owner datastore object, 
public abstract String getName( ) 

Gets query name. 

Returns: 
name of this server 
public abstract void setName(String name) 
. Sets query name. . 

Parameters: 

name — new name to be set to this server object 
The DKCQExpr class represents a compound or com- 
bined query expression. It may contain a DKQExpr 
query expressions tree, which may contain a combina- 



-continued 
public DKCQExprO 

public DKCQExpr(DKQExpr queryExpr) 

public short getQLTypeO 

public void setQUTypefshort qlType) 

public String getEtatastoreTypeQ 

public void setDatastoreType(String dsType) 

public String getDatastoreNameO 

public void setDatastoreNamefString dsName) 

public String getSearchTcmplateNarrieO 

public void setSearchIemplateName(String stName) 

public String[] getMappingNamesQ 

public intQ getMappingiypesO 

public String[] ge tEntity Names 0 

public boolean isTranslationO 

public DKQExpr getQueiyExprO 

public void setQueryExpr(DKQExpr queryExpr) 

} 



The following methods are part of the DKCQExpr class: 
public DKCQExpr( ) 

Default constructor without a parameter, 
public DKCQExpr(DKQExpr queryExpr) 

Constructor with one query expression, 
public short getQLType( ) 

Gets the query language type, which could be a 
parametric, text, image query, combined query, etc. 

Returns: 

the query language type, 
public void setQLType(short qlType) 
Sets the query language type. 
Parameters: 

qlType — the query language type 

See Also: 

getQLtype 
public String getDatastoreiype( ) 

Gets the target datastore type for executing this query. 
Returns: 

target datastore type 
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public void setDatastoreType(String dsType) 

Sets the target datastore type for executing this query. 
Parameters: 

dsName — target datastore type 
public String getDatastoreName( ) 5 
Gets the target datastore name for executing this query. 
Returns: 

target datastore name 
public void setDatastoreName(String dsName) 

Sets the target datastore name for executing this query. 10 
Parameters: 

dsName — target datastore name 
public String getSearchTemplateName( ) 

Gets the search template name origin of this query expres- 
sion. This data member is only applicable for query 15 
expressions originated from search templates. 

Returns: 

search template name 
public void setSearchTemplateName(String stName) 

Sets the search template name origin of this query expres- 20 
sion. This data member is only applicable for query 
expressions originated from search templates. 
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true if schema translation is required, 
public DKQExpr getQueryExpr( ) 

Gets the query expression. It could be a tree of DKQExpr 
query expressions connected by logical operator AND 
or OR. 

Returns: 

a query expression tree 
public void setQueryExpr(DKQExpr queryExpr) 

Sets the query expression tree. 
Parameters: 

queryExpr — a query expression tree 

See Also: 

getQueryExpr 

DKCombinedQueryDL is a class for a combined query 
(e.g., text and/or parametric and/or image) in a Digital 
Library/Visual Info datastore. An example class defi- 
nition for DKCombinedQueryDL is set forth below. 



DKCombitiedQueryDL 

package com.ibm.mm.sdk.common.DKCombinedQueryDL 
public class DKCombinedQueryDL extends Object 

implements dkQueryBase, DKMessageEd, DKCcnstani 

{ 

public DKCombiaedQueiyDLO 

public DKCombinedQueryDL(dkDatastore ds) 

public DKCombiaedQueryDL(DKCDmbuiedQueryDL fromQueiy) 

public void prepare(DKNVPaii paiams[]) throws DKException 

public void ocecute(DKNVPair params[J) throws DKException 

public int statusQ 

public Object resultQ 

public dkResultSctCursor results etCuison) throws DKException, Exception 
public int numberOfResults0 
public dkDatastore datastorcQ 
} 



Parameters: 

stName — the search template name 
public Stringf ] getMappingNames( ) 

Gets the optional schema mapping names for executing 45 

this query. The default value is null, which means 

mapping is not required. 
Returns: 

an array of mapping names. 5Q 
public int[ ] getMappingTypes( ) 

Gets the optional schema mapping types for executing 
this query. The default value is 0, which means map- 
ping is not required. Valid types are: 

DK_FED_MAPPED„ENTITY, DK_FED_ 55 
MAPPED_TEXT_ENT1TY, etc 

Returns: 

an array of mapping types, 
public String[ ] getEntityNames( ) 

Gets the mapped entity names in this query expression. 60 
. Returns: 

the array of mapped entity names, 
public boolean isTranslation( ) 

Check if this query requires schema translation using 65 
schema mapping. 

Returns: 



The following methods are part of the DKCombinedQue- 
ryDL class: 

public DKCombinedQueryDL( ) 

public DKCombinedQueryDL(dkDalastore ds) 

public DKCombinedQueryDL(DKCombinedQueryDL 

from Query) 

public void prepare(DKNVPair params[ ] throws DKExcep- 
tion 

public void execute(DKNVPair params[ ]) throws DKEx- 
ception 

Execute takes as many PQs+SCOPE_DLs and TQs+ 
SCOPE__TSs PQs run in parallel TQs run sequentially, 
one after the other using previous TQ results as scope 
for the current TQ The default operation is INTER- 
SECTS the results. 

public int status( ) 

public Object result( ) 

public dkResultSetCursor resultSetCursor( ) throws 
DKException, Exception 
public int numberOfResults( ) 

Gets the number of query results 

Returns: 

number of query results 
public dkDatastore datastore( ) 

DKTextQuery is used for a text query. An example class 
definition for DKTextQuery is set forth below. 
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DKTcxtQuery 

package com. ibm.mm.sdk. common. DKftxtQuery 
public class DKTbxtQuery 
extends Object 

implements dkQuery, DKConstant, DKMessageld, Serial izablc 

public DKTextQuery(dkDatastore creator, 

String queryString) 
public DKTextQuery(dkDatastore creator, 

DKCQExpr queryExpr) 
public DKTextQuery(DKTextQuery fromQuery) 

public void prepare (DKNVPair params[]) throws DKException, Exception 
public void exccute(DKNVPair paramsj]) throws DKException, Exception 
public int status Q 

public Object result() throws DKException, Exception 

public dkResultSetCursor resultSetcursorO throws DKException, Exception 

public short qliypeQ 

public String query StringQ 

public dkDatastore datastore 0 

public dkDatastore getDatastore() 

public void setDatastore{dkDatastore ds) throws DKException, Exception 

public String getName() 

public void setName(String name) 

public int numberOfResultsQ 

} 



The following methods are part of the DKTextQuery 
class: 

public DKTextQuery(dkDatastore creator, 

String querystring) 30 
Constructs a text query 
Parameters: 
creator — datastore 

queryString — a query string 35 
public DKTextQuery(dkDatastore creator, 
' DKCQExpr queryExpr) 
Constructs a text query 
Parameters: 

40 

creator — datastore 

queryExpr — a query expression 
public DKTextQuery(DKTextQuery from Query) 

Constructs a text query from a text query object 

Parameters: 45 

fromQuery — text query 
public void prepare(DKNVPair params[ ]) throws 
DKException, Exception 

Prepares the query. 

Parameters: 50 
params — additional prepare query option in name/value 
pair 

public void execute(DKNVPair params[ ]) throws 
DKException, Exception 5S 

Executes the query. 

Parameters: 

params — additional query option in name/value pair 
public int status( ) 

Gets query status. 60 

Returns: 

query status 

public Object result( ) throws DKException, Exception 
Gets query result. 65 
Returns: 

query result in a DKResults object 



public dkResultSetCursor resultSetCursor( ) throws 
DKException, Exception 

Gets query result. 

Returns: 

query result in a dkResultSetCursor object 
public short qlType( ) 

Gets query type. 

Returns: 

query type 
public String queryString( ) 

Gets query string 

Returns: 

query string 
public dkDatastore datastore( ) 

Gets the reference to the owner datastore object. Note: 
datastore( ) is deprecated. Replace by getdatastore. 

Returns: 

the dkDatastore object 
See Also: 
getDatastore 
public dkDatastore getDatastore( ) 

Gets the reference to the owner datastore object 
Returns: 

the dkDatastore object 
public void setDatastore(dkDatastore ds) throws 
DKException, Exception 

Sets the reference to the owner datastore object 

Parameters: 

ds — a Datastore 
public String getName( ) 

Gets query name 

Returns: 

name of this query 
public void setName(String name) 
Sets query name 
Parameters: 

name — new name to be set to this query object 
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public int numberOfResults( ) 
Gets the number of query results 
Returns: 

number of query results 5 
DKParametricQuery is used for a parametric query. An 

example class definition for DKParametricQuery is set 

forth below. 

10 

DKParametricQuery 

package com.ibm.mm.sdk. commoa DKParametricQuery 
public class DKParametricQuery 
extends Object 

implements dkQuery, DKConstaat, DKMessageld, Serializable 

{ 

public DKParamctricQueiy (dkDatastore creator, 

String queryString) 
public DKParametricQuery (dkDatas tore creator, 

DKCQExpr queryBxpi) 
public DKParametricQueiy (DKParametricQuery fromQuery) 20 
public void prepare (DKNVPair params[]) throws DKException, 
Exception 

public void execute(DKNVPair params[]) throws DKException, 

Exception 

public int statusQ 

public Object resultO throws DKException, Exception 25 
public dkResultSetCursor resultSetCursor() throws DKException, 
Exception 

public short qlTypeO 
public String queryStringQ 
public dkDatastore datastoreQ 

public dkDatastore getDatastoreO 3Q 
public void setDatastorefdkDatastore ds) throws DKException, 
Exception 

public String getNameO 

public void setName(String name) 

public int numberOfResultsQ 



The following methods are part of the DKParametric- 
Query class: 

public DKParametricQuery(dkDatastore creator, 

String queryString) 40 
Constructs a parametric query 
Parameters: 
creator — datastore 

queryString — a query string 45 
public DKParametricQuery(dkDatastore creator, 
DKCQExpr queryExpr) 
Constructs a parametric query 
Parameters: 

50 

creator — datastore 

queryExpr — a query expression 
public DKParametricQuery (DKParametricQuery 
fromQuery) 

Constructs a parametric query from a parametric query 55 

object 
Parameters: 

fromQuery — parametric query 
public void prepare(DKNVPair params[ ]) throws gQ 
DKException, Exception 

Prepares the query. 

Parameters: 

params — additional prepare query op don in name/value 
pair 65 
public void execute(DKNVPair params[ ]) throws 
DKException, Exception 
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Executes the query. 
Parameters: 

params — additional query option in name/value pair 
public int status( ) 
Gets query status. 
Returns: 
query status 

public Object result( ) throws DKException, Exception 
Gets query result. 
Returns: 

query result in a DKResults object 
public dkResultSetCursor resultSetCursor( ) throws 
DKException, Exception 

Gets query result. 
Returns: 

query result in a dkResultSetCursor object 
public short qlType( ) 

Gets query type. 

Returns: 

query type 
public String queryString( ) 

Gets query string 

Returns: 

query string 
public dkDatastore datastore( ) 

Gets the reference to the owner datastore object. Note: 

datastore( ) is deprecated. Replace by getdatastore. 
Returns: 

the dkDatastore object 
See Also: 
getDatastore 
public dkDatastore getDatastore( ) 

Gets the reference to the owner datastore object 
Returns: 

the dkDatastore object 
public void setDatastore(dkDatastore ds) throws 
DKException, Exception 

Sets the reference to the owner datastore object 
Parameters: 
ds — a Datastore 
public String getName( ) 
Gets query name 
Returns: 

name of this query 
public void setName(String name) 
Sets query name 
Parameters: 

name — new name to be set to this query object 
public int numberOfResults( ) 
Gets the number of query results 
Returns: 

number of query results 

DKImageQuery is used for an image query. An example 
class definition for DKImageQuery is set forth below. 
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p KtmageQucry 

package com.ibm.mm.sdk.cominoaDKImageQuery 
public class DKImageQueiy 
extends Object 

implements dkQuery, DKConstant, DKMessageld, Serializable 

{ 

public DKIrnageQuery(dkDatastore creator, 

String queryString) 
public DKImageQuery(dkDatastore creator, 

DKCQEXpr queryExpr) 
public DKIrnageQuery(DKImageQuery fromQuery) 
public void prepare(DKNVPair params[]) throws DKException, 
Exception 

public void execute(DKNVPair params[I) throws DKException, 

Exception 

public int status 0 

public Object result0 throws DKException, Exception 

public dkResultSetCursor resultSetCursorO throws DKException, 

Exception 

public short qliype() 
public String queryStringO 
public dkDatastore datastoreO 
public dkDatastore getDatastoreO 

public void setDatastore(dkDatastore ds) throws DKException, 
Exception 

public String getNameO 
public void setName(String name) 
public int numbcrOfResultsQ 
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} 
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The following methods are part of the DKImageQuery 
class: 30 
public DKImageQuery(dkDatastore creator, 

String queryString) 

Constructs a image query 

Parameters: 35 

creator — datastore 

queryString — a query string 
public DKImageQuery(dkDatastore creator, 

DKCQExpr queryExpr) 

Constructs a image query 

Parameters: 

creator — datastore 

queryExpr — a query expression 
public DKImageQuery(DKImageQuery fromQuery) 

Constructs a image query from a image query object 

Parameters: 

fromQuery — image query 
public void prepare(DKNVPair params[ ]) throws 
DKException, Exception 

Prepares the query. 

Parameters: 

params — additional prepare query option in name/value 
pair 55 
public void execute(DKNVPair params[ ]) throws 
DKException, Exception 

Executes the query. 

Parameters: 

params — additional query option in name/value pair 60 
public int status( ) 
Gets query status. 
Returns: 

query status 65 
public Object result( ) throws DKException, Exception 
Gets query result. 



Returns: 



query result in a DKResults object 
public dkResultSetCursor resultSetCursor( ) throws 
DKException, Exception 

Gets query result. 

Returns: 

query result in a dkResultSetCursor object 
public short qlType( ) 

Gets query type. 

Returns: 

query type 
public String queryString( ) 

Gets query string 

Returns: 

query string 
public dkDatastore datastore( ) 

Gets the reference to the owner datastore object. Note: 
datastore( ) is deprecated. Replace by getdatastore. 

Returns: 

the dkDatastore object 
See Also: 
getDatastore 
public dkDatastore getDatastore( ) 

Gets the reference to the owner datastore object 
Returns: 

the dkdatastore object 
public void setDatastore(dkDatastore ds) throws 
DKException, Exception 

Sets the reference to the owner datastore object 
public String getName( ) 

Gets query name 

Returns: 

name of this query 
public void setName(String name) 
Sets query name 
Parameters: 

name — new name to be set to this query object 
public int numberOfResults( ) 
Gets the number of query results 
Returns: 

number of query results 

DKSQLQuery is used for a SQL query. An example class 
definition for DKSQLQuery is set forth below. 
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DKSQLQuery 

package com.ibm.mm.sdk.common. DKSQLQuery 
public class DKSQLQuery 
extends Object 

implements dkQuery, DKConstant, DKMessagetd, Serializable 

public DKSQLQueryfdkDatastore creator, 

String queryString) 
public DKSQLQueryfdkDatastore creator, 

DKCQExpr queryExpr) 
public DKSQLQucry(DKSQLQuery fromQuery) 
public void prepare(DKNVPair paramsQ) throws DKException, 
Exception 

public void executc(DKNVPair params[D throws DKException, 

Exception 

public int status 0 

public Object resultQ throws DKException, Exception 
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-continued 

public dkResultSetCursor lesultSetCursorO throws DKException, 
Exception 

public short qtTypef) 
public String queryStringO 
public dkDatastoie datastoreQ 
public dkDatastore gctDatastorcQ 

public void setDatastore(dkDatastore ds) throws DKException, 
Exception 

public String getNameO 
public void setName (String name) 
public int numberOfResultsO 
} 



The following methods are part of the DKSQLQuery 
class: 

public DKSQLQuery (dkDatastore creator, 
String queryString) 

Constructs a sql query 

Parameters; 

creator — datastore 

queryString — a query string 
public DKSQLQuery(dkDatastore creator, 

DKCQExpr queryExpr) 

Constructs a sql query 

Parameters: 

creator — datastore 

queryExpr — a query expression 
public DKSQLQuery(DKSQLQuery fromQuery) 

Constructs a sql query from a sql query object 

Parameters: 

fromQuery — sql query 
public void prepare(DKNVPair params[ ]) throws 
DKException, Exception 

Prepares the query. 

Parameters: 

params — additional prepare query option in name/value 
pair 

public void execute(DKNVPair params[ ]) throws 
DKException, Exception 

Executes the query 

Parameters: 

params — additional query option in name/value pair 
public int status( ) 
Gets query status. 
Returns: 
query status 

public Object result( ) throws DKException, Exception 
Gets query result. 
Returns: 

query result in a DKResults object 
public dkResultSetCursor resultSetCursor( ) throws 
DKException, Exception 

Gets query result. 

Returns: 

query result in a dkResultSetCursor object 
public short qlType( ) 

Gets query type. 

Returns: 

query type 
public String queryString( ) 
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Gets query string 
Returns: 
query string 
public dkDatastore datastore( ) 

Gets the reference to the owner datastore object. Note: 

datastore( ) is deprecated. Replace by getdatastore. 
Returns: 

the dkDatastore object 
10 . See Also: 
getDatastore 
public dkDatastore getDatastore( ) 

Gets the reference to the owner datastore object 
25 Returns: 

the dkDatastore object 
public void setDatastore(dkDatastore ds) throws 
DKException, Exception 
Sets the reference to the owner datastore object 
20 public String getName( ) 
Gets query name 
Returns: 

name of this query 
25 public void setName(String name) 
Sets query name 
Parameters: 

name — new name to be set to this query object 
3Q public int numberOfResults( ) 

Gets the number of query results 
Returns: 

number of query results 
16. Query Expressions 

35 A query expression is used to specify a simple query. It is 
an alternate form of a query string. It may have one or more 
sub-query expressions (DKQSubExpr). Each sub-query 
expression has a query term (DKQTerm), an option list, and 
a parameter list. The query term specifies the query condi- 

40 tions The option list specifies options relevant to the query. 
An example of an option in DL could be the maximum result 
limit of this query. The parameter list specifies parameters to 
be used by or bound to the query. The query language type 
indicates if it is parametric, text or image query. User can 

45 combine two query expressions with logical operator AND 
to form a query expression tree. Logical operator OR is not 
supported yet. A DKQExpr can represents either a query 
expression or expression tree. An expression tree has posi- 
tive opcode( ), and non-null left( ) and right( ) subtree. A 

50 DKQExpr is singular if opcode( ) is negative, and left( ) and 
right( ) are null. Currently, the expression tree can only 
contains a maximum of one parametric, one text, and one 
image query. 

An example class definition for DKQExpr is set forth 
55 below. 



DKQExpi 

package com. ibm.mm.sdkcommon. DKQExpr 
public class DKQExpr 

extends Object 

implements Serializable 

{ 

public DKQExprO 
public DKQExpr(DKQExpr lhs, 
short logOpCode, 
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DKQExpr rhs) 
public short getQUypeO 
public void setQLiypefshort qliype) 
public String getDatastoreiypeO 
public void eetDatastoreType(String dsType) 
public String gctDatastorcNamcQ 
public void fietDatastoreNameCString dsName) 
public boolean isTranslationO 
public String[ ] getMappingNamesO 
public int[] getMappingiypesQ 
public String getAssociatedMappingO 

public void setAssociatedMapping(String associatedMapping) 

public String[] getEntityNamesO 

public int subQucryCountO 

public int addSubQueiy(DKQSubExpr subQE) 

public int rcmovcSubQucry(DKQSubExpr subQE) 

public void iemoveSubQuery(int position) 

public DKQSubExpr getSubQuery(int position) 

public int optionCountO 

public DKNVPair[] getOptiooListO 

public void setOptionListfDKNVPair optioaList[J} 

public DKNVPair getOption(int position) 

public DKNVPair getOption(String name) 

public void sctOption(int position, 

DKNVPair optionPaii) 
public int setOption(String name, 

Object value) 
public void iemoveOption(int position) 
public int removcOption(String name) 
public int parametcrCountQ 
public DKNVPairQ getParameterList() 
public void sctParamctciList(DKNVPair paramctcrList[J) 
public DKNVPair getParametei(int position) 
public DKNVPair getParametei(String name) 
public void setParameter(int position, 

DKNVPair pannPaii) 
public int setParameter(StrLng name, 

Object value) 
public void removeParametei(int position) 
public int removeParameter(String name) 
public short opCo deQ 
public DKQEXpr leftO 
public DKQEXpr rightO 
public boolean isLeafQ 
public DKQExpr and(DKQExpr rhs) 
public DKQExpr or(DKQExpr rhs) 
} 



The following methods are part of the DKQExpr class: 
public DKQExpr( ) 

Default constructor without a parameter, 
public DKQExpr(DKQExpr lhs, 

short logOpCode, 

DKQExpr rhs) 

Creates a query expression tree by applying a logical 

operator to a pair of query expressions. 
Parameters: 
lhs — left query 

logOpCode — logical operator code 
rhs — right query 
public short getQLType( ) 

Gets the query language type, which could be a 

parametric, text image query, etc. 
Returns: 

the query language type 
public void setQLType(short qlType) 

Sets the query language type, which could be a 

parametric, text, image query, etc. 
Parameters: 

qlType — the query language type 
public String getDatastoreType( ) 



10 



15 



25 



Gets the target datastore type for executing this query. 
Returns: 

target datastore type 
public void setDatastore iype(String dsiype) 

Sets the target datastore type for executing this query. 
Parameters: 

dsName — target datastore type 
public String getDatastoreName( ) 

Gets the target datastore name for executing this query. 
Returns: 

target datastore name 
public void setDatastoreName(String dsName) 

Sets the target datastore name for executing this query. 
Parameters: 

dsName — target datastore name 
public boolean isTranslation( ) 

Check if this query requires a translation using schema 

mapping. 
Returns: 

true if schema translation is required, 
public Stringf ] getMappingNames( ) 

Gets the optional schema mapping names for executing 
this query. The default value is null, which means 
mapping is not required. 
Returns: 

the array of mapping names, 
public int[ ] getMappingTypes( ) 

Gets the optional schema mapping types for executing 
this query. The default value is 0, which means map- 
ping is not required. Valid types are: DK_JFED_ 
MAPPED_ENTITY, DK_FED_MAPPED_TEX__ 
ENTITY, etc 
Returns: 

the array of mapping types, 
public String getAssociatedMapping( ) 
40 Gets the associated mapping for this query expression. 
Only applicable for text query. 
Returns: 

the associated mapping 
45 public void setAssociatedMapping(S tring 
associatedMapping) 
Sets the associated mapping for this query expression 

Only applicable for text query. 
Parameters: 

the — associated mapping 
public String[ ] getEntityNames( ) 

Gets the mapped entity names in this query expression. 
Returns: 

the array of mapped entity names, 
public int sub Query Count( ) 

Gets the number of sub-queries in this expression. 
Returns: 

the number of sub-queries, 
public int addSubQuery(DKQSubExpr subQE) 
Adds a sub-query to this expression. 
Returns: 

number of sub -queries in this expression, 
public int removeSubQuery(DKQSubExpr subQE) 
Removes a given sub-query form this expression. 
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Returns: 

the position of removed sub-query, 
public void removeSubQuery(int position) 

Removes a sub-query at the given position form this 
expression. 

public DKQSubExpr getSubQuery(int position) 
Gets the sub-query at the given position. 
Returns: 

the sub -query object 
public int optioncount( ) 

Gets the number of denned options. 
Returns: 

integer number of options 
public DKNVPair[ ] getOptionList( ) 
Gets the option list. 
Returns: 

an NVPair array of options, 
public void setOptionList(DKNVPair optionList[ ]) 
Sets the option list. 
Parameters: 

an — NVPair array of options, 
public DKNVPair getOption(int position) 

Gets an option at the given position. 

Throws: IndexOutOfBoundsException 

if position is invalid, 
public DKNVPair getOption(String name) 

Gets an option with a given name. 

Returns: 

the option with the given name; or null if it is not found, 
public void setOption(int position, 
DKNVPair optionPair) 
Sets the option at the given position. 
Parameters: 

optionPair — the new option 
Throws: IndexOutOfBoundsException 
if position is invalid, 
public int setOption(String name, 
Object value) 

Sets the option with the given name. The option will be 4S 

added, if it does not exist yet. 
Returns: 

the position of the option 
public void removeOption(int position) 
Removes the option at the given position. 
Parameters: 
the — position. 

Throws: IndexOutOfBoundsException 
if position is invalid, 
public int removeOption(String name) 
Removes the option with the given name. 
Parameters: 

name — the option name. 
Returns: 

the position; -1 if not found. 
Throws: IndexOutOfBoundsException 
if position is invalid, 
public int parameterCount( ) 

Gets the number of denned parameters. 
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Returns: 

integer number of parameters 
public DKNYPairt ] getParameterList( ) 
Gets the parameter list. 
Returns: 

an NVPair array of parameters, 
public void setParameterList(DKNVPair parameterListf ]) 
Sets the parameter list. 
Parameters: 

an — NVPair array of parameters, 
public DKNVPair getParameter(int position) 
Gets a parameter at a given position. 
Throws: IndexOutOfBoundsException 
if position is invalid, 
public DKNVPair getParameter(String name) 
Gets a parameter with a given name. 
Returns: 

the option with the given name; or null if it is not found, 
public void setParameter(mt position, 
DKNVPair parmPair) 
Sets the parameter at the given position. 
Parameters: 

parmPair — the new parameter 
Throws: IndexOutOfBoundsException 
if position is invalid, 
public int setParameter(String name, 
Object value) 

Sets a parameter with a given name. The parameter will 

be added, if it does not exist yet. 
Returns: 

the position of the parameter 
public void removeParameter(int position) 
Removes the parameter at the given position. 
Parameters: 
the — position. 

Throws: IndexOutOfBoundsException 
if position is invalid, 
public int removeParameter(String name) 
Removes the parameter with the given name. 
Parameters: 

name — the parameter name. 
Returns: 

the position; -1 if not found. 
Throws: IndexOutOfBoundsException 
if position is invalid, 
public short opCode( ) 

Gets the operator code in tHis expression tree. 
Returns: 

the operator code 
public DKQExpr left( ) 

Gets the query in left hand side. 
Returns: 
left query 
public DKQExpr right( ) 

Gets the query in right hand side. 
Returns: 
right query 
public boolean is Leaf ( ) 

Check if this expression is a leaf. 
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Returns: 

true if this is a leaf, 
public DKQExpr and(DKQExpr rhs) 
Applies logical AND operator between this query expres- 
sion and another one. 
Parameters: 

rhs — the query to be AND-ed at the right hand side 
Returns: 

a new resulting query 
public DKQExpr or(DKQExpr rhs) 

Applies logical OR operator between this query and 

another one. 
Parameters: 

rhs — the query to be OR-ed at the right hand side 
Returns: 

a new resulting query 

A sub-query DKQSubExpr expression consists of entity- 
names, a display-list, a query term, an option list, and an 
optional parameter list. A query expression DKQExpr may 
contains one or more sub -expressions, each sub-expression 
essentially defines a sub-query. When the query is executed, 
each sub-query will be executed and the results will be 
OR-ed together to form a result for the whole query. Digital 
Library datastore supports sub-queries as described above, 
but not all datastores support sub-queries. In such a case, 
there will bw only one sub-query. 

An example class definition for DKQSubExpr is set forth 
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Object value) 
public void temoveParametei(int position) 
public int removeParatneter(String name) 
} 
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DKQSubExpr 

package com. Lb m.mm.sdk. common .DKQSubExpr 
public class DKQSubExpr 

extends Object 

implements Serial izable 

{ 

public DKQSubExprO 

public String gctEntxtyNameO 

public void setEntityName(String name) 

public String!] gttEntityNamesO 

public void setEntityNamcs(String names[J) 

public String getMappingName0 

public void setMappingName(String mappingName) 

public int getMappingTypeO 

public void setMappingType(int mappingType) 

public boolean isTranslationO 

public void setTrans]ation(boalean translation) 

public String[] getDisplayList() 

public void setDisplayList(String names[]) 

public DKQTerm getQueryTermO 

public void setQueryTerm(DKQ1brm qTerm) 

public int optionCountQ 

public DKNVPair[] getOptionListQ 

public void setOptionUst(DKNVPair optionlistfj 

public DKNVPair getOption(int position) 

public DKNVPair getOption(String name) 

public void setOption(int position, 

DKNVPair optionPair) 
public int setOption (String name, 

Object value) 
public void removeOptionfint position) 
public int removeOption(Stiing name) 
public int parameterCountQ 
public DKNVPair[J getParametcrListO 
public void setParameterList(DKNVPair parameterListf]) 
public DKNVPair getParametei(int position) 
public DKNVPair gctParametei(String name) 
public void setParameter(int position, 

DKNVPair parmPair) 
public int setParameter(String name, 
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The following methods are part of the DKQSubExpr 
class: 

public DKQSubExpr( ) 

Default constructor without a parameter, 
public String getEntityName( ) 

Gets the entity-name specified in this query. Assumes that 

there is only one entity involved. 
Returns: 

the entity name, or null if the entity-name is not initial- 
ized, 

public void setEntityName(String name) 

Sets the entity-name in this query. Assumes that there is 

only one entity involved in this query. 
Parameters: 
the — entity name. 
25 public String[ ] getEntityNames( ) 

Gets the entity-names ia this query; there are more than 
one entity-names. For example, a text query may have 
more than one entity or search-indices specified. 
Returns: 

30 a string array of entity names, or null if the entity-name 
is not initialized, 
public void setEntityNames(String names[ ]) 
Sets the entity-names in this query; there are more than 

one entity-names. 
Parameters: 

values — a string array of entity names, 
public String getMappingName( ) 

Gets the optional schema mapping name for executing 
this query. The default value is null, which means 
mapping is not required. 
Returns: 

the mapping name, 
public void setMappingName(String mappingName) 
Sets the optional schema mapping name for executing this 

query. 
Parameters: 

mappingName — the mapping name 
public int getMappingiype( ) 

Gets the optional schema mapping type for executing this 
query. The default value is 0, which means mapping is 
not required. Valid values are: DK_FED_MAPPED_ 
ENTITY, DK_FED_MAPPED_TEX_ENTITY, etc 
Returns: 
the mapping type, 
public void setMappingType(int mappingType) 

Sets the optional schema mapping type for executing this 
query. 
60 Parameters: 

mappingName — the mapping name 
See Also: 
getMappingtype 
65 public boolean isTranslation( ) 

Check if this query requires schema translation using 
schema mapping. 
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Returns: 

true if schema translation is required, 
public void setTranslation(boolean translation) 

Sets the requirement for schema translation for this query. 

Schema mapping name must by provided via 5 

setMappingName( ) method. 
Parameters: 

translation — true or false. 

See Also: 10 

isTranslation, setMappingname 
public String[ ] getDisplayUst( ) 

Gets the display-list in this query. The display-list is a list 
of search attribute -names to be displayed in the results 
of this query. If it is not specified, all attributes will be 15 
selected. 

Returns: 

a string array of attribute-names, or null if display-list is 
not initialized. 2q 
public void setDisplayList(String namesf ]) 
Sets the display-list in this query. 
Parameters: 

names — a string array of attribute-names. 

See Also: 

getDisplaylist 
public DKQTenn getQueryTerm( ) 

Gets the query term or condition part of this query. 

Returns: 30 

a DKQTerm object 
public void setQueryTerm(DKQTerm qTerm) 

Sets the query term or condition part in this query. 

Parameters: 35 

a— DKQTerm object 
public int optionCount( ) 

Gets the number of defined options. 

Returns: 

integer number of options 
public DKNYPairt ] getOptionList( ) 
public void setOptionList(DKNVPair optionList[ ]) 
public DKNVPair getOption(int position) 

Gets an option at the given position. 45 

Throws: IndexOutOfBoundsException 

if position is invalid, 
public DKNVPair getOption(String name) 

Gets an option with a given name. 

Returns: 50 
the option with the given name; or null if it is not found, 
public void setOption(int position, 
DKNVPair optionPair) 

Sets the option at the given position. S5 
Parameters: 

optionPair — the new option 
Throws: IndexOutOfBoundsException 
if position is invalid, 
public int setOption(String name, 
Object value) 

Sets the option with the given name. The option will be 

added, if it does not exist yet. 
Returns: 65 
the position of the option 
public void removeOption(int position) 
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Removes the option at the given position. 

Parameters: 

the — position. 

Throws: IndexOutOfBoundsException 
if position is invalid, 
public int removeOption(String name) 
Removes the option with the given name. 
Parameters: 

name — the option name. 
Returns: 

the position; -1 if not found. 
Throws: IndexOutOfBoundsException 
if position is invalid, 
public int parameterCount( ) 

Gets the number of defined parameters. 
Returns: 

integer number of parameters 
public DKNVPairf ] getParameter!ist( ) 
public void setParameterList(DKNVPair parameterList[ ]) 
public DKNVPair getParameter(int position) 

Gets a parameter at a given position. 

Throws: IndexOutOifBoundsException 

if position is invalid, 
public DKNVPair getParameter(String name) 

Gets a parameter with a given name. 

Returns: 

the option with the given name; or null if it is not found, 
public void setParameter(int position, 
DKNVPair parmPair) 
Sets the parameter at the given position. 
Parameters: 

parmPair — the new parameter 
Throws: IndexOutOfBoundsException 
if position is invalid, 
public int setParameter(String name, 
Object value) 

Sets a parameter with a given name. The parameter will 

be added, if it does not exist yet. 
Returns: 

the position of the parameter 
public void removeParameter(int position) 
Removes the parameter at the given position. 
Parameters: 
the — position. 

Throws: IndexOutOfBoundsException 
if position is invalid, 
public int removeParameter(String name) 
Removes the parameter with the given name. 
Parameters: 

name — the parameter name. 
Returns: 

the position; -1 if not found. 
Throws: IndexOutOfBoundsException 
if position is invalid. 

Query terms are used to represent a predicate logic 
expression in a query. A basic query term can be as simple 
as a text string (as part of a text query) or a pair of attribute 
name and value separated by a comparison operator: =, >, 
>=, <, <=, <>, BETWEEN, LIKE, IN. Query terms can be 
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combined together with logical operators : AND, OR, NOT. 
This class does not support operators: NOUN, NOTLIKE, 
NOTBETWEEN, however, user can create an equivalent 
expression using NOT logical operator. 

An example class definition for DKQTerm is set forth 
below. 



DKQTerm 



package comabm.tnm.sdk.common.DKQTerm 
public class DKQTerm 
extends Object 

implements Serializable, Cloneable 

{ 

public DKQTermO 

public DKQTerm(String stringTenn) 

public DKQTerm(String stringTenn, 

DKNVPaLr options[D 
public DKQTerm(String attrName, 
short cmpOpCode, 
String attr Value) 
public DKQTerm(Stxing attrName, 
short cmpOpCode, 
String attrValuesfJi 
public DKQTerm(DKQTenn leftTerm, 
short logOpCodc, 
DKQTerm rightTerm) 



publi 
publi 
publi 
publi 
publi 
publi 
publi 
publi 
publi 
publ: 
publi 
publi 
publi 
publi 
publi 
publi 
publi 
publi 
publi 
publ: 
publ: 
publi 
publ 
publ: 
} 



c short getOpCodeO 
c void setOpCode(short opCode) 
c DKQTerm getLeft() 
c void setLefi(DKQTenn Left) 
;c DKQTerm getRightO 
!c void setRight(DKQTerm right) 
;c DKQTerm and(DKQTerm rhs) 
c DKQTerm or(DKQTerm rhs) 
c DKQTerm notO 
c boolean isNotTermO 
c booleaa isLeafO 
c String getStringlbrmO 
c void setStringTerm (String stiingTerm) 
c String getNamef) 
c void setName(String attrName) 

String get\&hie0 

void setValuefString value) 
c Stringf] get Values 0 
c void setValues (String values[]) 
c boolean hasMultiValuesO 
c DKNVPair[] getOptionsO 
c void setOptions(DKNVpair options[D 
c String toStringO 
c Object cloneQ 
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The following methods are part of the DKQTerm class: 
public DKQTerm( ) 

Default constructor, 
public DKQTerm(String stringTenn) 

Creates a query term based on the string input. 
Parameters: 

stringTenn — a text query string term, 
public DKQTerm(String stringTenn, 
DKNVPair options[ ]) 
Parameters: 

stringTenn — a text query string term, 
options — options applicable to this term, for example in 
the test 

string the options could be CCSID, wildcard char, etc. 
public DKQTerm(String attrName, 
short cmpOpCode, 
String attrValue) 

Creates a term specifying a query condition to be met. 



50 



55 



60 



65 



Parameters: 

attrName — attribute name in this conditional expression 
cmpOpCode — comparison operator code, that is, >, 
etc. 

attrValue — attribute value 
public DKQTerm(String attrName, 
short cmpOpCode, 
String attrValues[ ]) 

Creates a term specifying a query condition to be met. It 
takes an anay of values as input for handling operators 
requiring more than one value, like BETWEEN, IN, 
etc. 

Parameters: 

attrName — attribute name in this conditional expression 
cmpOpCode — comparison operator code which takes 

more than one values. 
attrVahies — attribute value array 
public DKQTerm(DKQTerm leftTerm, 
short logOpCode, 
DKQTerm rightTerm) 

Creates a term specifying a query condition to be met. It 
takes two terms, left and right term with a logical 
operator. Old terms will be absorbed by the new term. 

Parameters: 

leftTerm — left term 

logOpCode — logical operator code 

rightTerm — right term 
public short getOpCode( ) 

Gets the operator code in this term. 

Returns: 

the operator code in this term 
public void setOpCode(short opCode) 

Sets the operator code in this term. The caller is respon- 
sible to make sure that the operator is appropriate for 
this term. 

Parameters: 

opCode — the operator code for this term 
public DKQTerm getLeft( ) 

Gets the left hand side part of this term. 

Returns: 

left term, 
public void setLeft (DKQTerm left) 

Sets the left hand side part of this term. The caller is 
responsible to make sure that the lhs term is appropriate 
for this term. 

Parameters: 

left— the left term, 
public DKQTerm getRight( ) 

Gets the right hand side part of this term. 

Returns: 

right term, 
public void setRight(DKQTerm right) 
Sets the right hand side part of this term. The caller is 
responsible to make sure that the rhs term is appropriate for 
this term. 

Returns: 

right term, 
public DKQTerm and(DKQTerm rhs) 

Applies logical AND operator between this term and 
another given term. 
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Parameters: 

rhs — the term to be AND-ed at the right hand side 
Returns: 

a new resulting term 
public DKQTerm or(DKQTerm rhs) 
Applies logical OR operator between this term and 

another given term. 
Parameters: 

rhs — the term to be OR-ed at the right hand side 
Returns: 

a new resulting term 
public DKQTerm not( ) 
Apply logical NOT operator to this term, that is, negate 
this term. This term will be the rhs of the resulting term. 
Returns: 

a new resulting term 
public boolean isNotTerm( ) 
Check if this term is negated. 
Returns: 

true if this term is negated, 
public boolean isLeaf( ) 
Check if this term is a leaf. 
Returns: 

true if this term is a leaf, 
public String getStringTerm( ) 

Gets the string part of this term. 

Returns: 

the string part 
public void setStringTerm(String stringTerm) 

Sets the string part of this term. 

Parameters: 

stringTerm — the string part 
public String getName( ) 

Example, 'Anonymous^VJohn Smith \",\"Mary J s 
LambY\ 

Returns: 

the value part of this term; or null if the value is not 

initialized, 
public void setValue(String value) 

Sets the value part of this term. Assumes that the new 

value is one value. 
Parameters: 

the — new value of this term 
See Also: 
getvalue 
public String[ ] getValues( ) 

Gets the value part of this term; there are more than one 
values. 

Returns: 55 
a string array of values; or null if the attribute value is not 
initialized, 
public void setValues(String values[ ]) 

Sets the value part of this term; there are more than one 

values. 60 
Parameters: 

values — a string array of values, 
public boolean hasMultiValues( ) 
Check if this term has multi-values. 
Returns: 

true if term has multi values 
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public DKNVPair[ ] getOptions( ) 

Gets options defined in this term. Options only applicable 
to text query term. 
< Returns: 
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an array of DKNVPair object each indicating option name 
and value. 

public void setOptions(DKNVPair optionsf ]) 
Sets options for this term. 
Parameters: 

options — an array of DKNVPair object each indicating 

option name and value. 
See Also: 
getOptions 
public String toString( ) 

Re-constructs the string form of this query expression 
with the correct levels of required parentheses. Siring 
attribute values are assumed to have the correct pair of 
quotes, for example, * Anonymous', Y'John SmithV, 
Y'Mary's LambV. 

Returns: 

the string form of this query expression 
Overrides: 

toString in class object 
public Object clone( ) 
Overrides: 

clone in class object 
17. Iterators 

dklterator is the base interface for iterators. It is used to 
iterate over collection members, dklterator is sub- 
classed to provide suitable implementation for each 
collection type. An example class definition for dklt- 
erator is set forth below. 
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dklterator 

package com.ibm.mrn.edk.comrnon.dklterator 

public interface dklterator 

{ 

public abstract Object nextQ throws DKUsageError 
public abstract void resetO 
public abstract boolean moreQ 



The following methods are part of the dklterator class: 
public abstract Object next( ) throws DKUsageError 

Gets the current element in the collection and advances 
the iterator to the next element 

Returns: 

current element, 
public abstract void reset( ) 

Resets the iterator to the beginning of the collection, 
public abstract boolean more( ) 

Returns true if there are more elements in the collection. 

Returns: 

true or false. 

A sequential iterator is bi-directional; it can go forward 
and backward over members of a collection that sup- 
ports it. An example class definition for DKSequenti- 
allterator is set forth below. 
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DKSequentiaUtcrator 

package com.ibm.mm.sdltcommon.DKSequentialIterator 
public interface DKSequentiallterator 
extends dklterator 

{ 

public abstract Object previous Q throws DKUsageError 

public abstract boolean setToFirstO 

public abstract boolean setTbLastO 

public abstract boolean setToNext() 

public abstract boolean setToPrcviousO 

pubtic abstract Object atQ throws DKUsageError 

} 
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User-id and password mapping. To support single sign-on 
features, each user-id in the federated datastore 100 
needs to be mapped to its corresponding user-ids in the 
native datastores. 
Datastore registration. Each native datastore needs to be 
registered so it can be located and logged-on to by the 
federated datastore 100 processes on behalf of its users. 
dkSchemaMapping is the an interface to define an 
associative mapping between a mapped or federated 
entity and a map-to or native entity in back-end 
datastores, An example class definition for dkSche- 
maMapping is set forth below. 



The following methods are part of the DKSequentiallt- 
erator class: 

public abstract Object previous( ) throws DKUsageError 

Gets the current element in the collection and repositions 
the iterator to the previous element. 

Returns: 

current element, 
public abstract boolean setToFirst( ) 

Sets to the first element in the collection. 

Returns: 

true if position is valid, 
public abstract boolean setToLast( ) 

Sets to the last element in the collection. 
Returns: 

true if position is valid, 
public abstract boolean setToNext( ) 

Sets to the next element in the collection. 
Returns: 

true if position is valid, 
public abstract boolean setToPrevious( ) 

Sets to the previous element in the collection. 
Returns: 

true if position is valid, 
public abstract Object at( ) throws DKUsageError 

Gets the current element in the collection. 

Returns: 

current element. 
18. Schema Mapping 

A schema mapping represents a mapping between the 
schema in a datastore with the structure of the data-object 
that the user wants to process in memory. Schema mapping 
has been generally described in U.S. patent application Ser. 
Nos. 08/276,382 and 08/276,747, also assigned to IBM. 

A federated schema is the conceptual schema of a feder- 
ated datastore 100, which defines a mapping between the 
concepts in the federated datastore 100 to concepts 
expressed in each participating datastore schema In general, 
a schema mapping handles the difference between how the 
data are stored in the datastore (as expressed by the datas- 
tore's conceptual schema) and how the user wants to process 
them in the application program. This mapping can also be 
extended to incorporate relationship associations among 
entities in a federated datastore, e.g., associating an employ- 
ee's name with the appropriate department name. Since the 
mapping process can be a bit tedious, it is usually done with 
the help of a typical GUI-oriented schema mapping pro- 
gram. 

In addition to schema-mapping information involving the 
mapping of entities and attributes, a federated datastore 100 
must also have access to the following information: 



15 

dkSchemaMapping 

package com. ibm.rnm.sdkcommon. dkSchemaMapping 
public interface dkSchemaMapping 

2Q public abstract String getNameO 

public abstract void setName(String name) 

public abstract String getServerNameO 

public abstract void setServeiName(String serverName) 

public abstract String getServeriypeO 

public abstract void setServerType(String serverType) 

public abstract String getEntityNameQ 

public abstract void setEntityNaine(String nativeEatityName) 

public abstract String getMappedEntityNameQ 

public abstract void setMapped^arityName(String 

mappedEntityName) 

public abstract short getMappedEntityTypeQ 

public abstract void sctMappedEntityType(short mappedEntityType) 
30 public abstract String getAssocMappedEntityNameO 

public abstract void setAssocMappedEntityName(String 

assocMappcdEntityName) 

public abstract String getAssocEntityName() 

public abstract void setAssocEntityName(String 

assocNativeEntityName) 
35 public abstract String getAssocServerName() 

public abstract void setAssocServerName(String assocServerName) 

public abstract dkAttrMapping getAttrMapping(String 

attrMappingName) throws DKException 

public abstract dkCollection listAttrMappingsf) throws DKException 
public abstract String! ] lis (AttrMappingNamesQ throws 

4Q DKException 

public abstract void retrieveO throws DKException 
public abstract dkAttrMapping getAttrMappingByMappedName 
(String map pedAttr Name) 
throws DKException 
public abstract dkAttrMapping getAttrMappingByMapToName(String 

45 mapTbAttrName) 

throws DKException 

} 



The following methods are part of the dkSchemaMapping 
class: 

public abstract String getName( ) 

Gets the name of this SchemaMapping object 
Returns: 

name of this object 
55 public abstract void setName(String name) 

Sets the name of this SchemaMapping object 
Parameters: 

extName — name of this SchemaMapping object 
6Q public abstract String getServerName( ) 

Gets the name of the server where native attributes are 

defined. 
Returns: 
server name 

65 public abstract void setServerName(String serverName) 
Sets the name of the server where native attributes are 
defined. 
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Parameters: 

server Name — back-end server name 
public abstract String getServerType( ) 

Gets the type of the server where native attributes are 

defined. It could be one of DIC_DL„DSTYPE, 5 

DK__OD_DSTYPE, etc 
Returns: 
server type 

public abstract void setServerType(String serverType) 1Q 
Sets the type of the server where native attributes are 

defined. 
Parameters: 

serverType — server type 
public abstract String getEntityName( ) 15 
Gets the name of the native entity. 
Returns: 

native entity name, for example this could be the index 
class name if the server type is DL/VI, or it could be the 
application group name if the server type if OnDe- 
mand. 

public abstract void setEntityName(String 
nativeEntityName) 

Sets thename of the native entity. ^ 

Parameters: 

nativeEntityName — name of the native entity (index class 
name for example) 
public abstract String getMappedEntityName( ) 

Gets the name of the mapped or federated entity. 30 
Returns: 

federated entity name 
public abstract void setMappedEntityName(String 
mappedEntityName) 

Sets the name of the mapped or federated entity. 35 

Parameters: 

mappedEntityName — federated entity name 
public abstract short getMappedEntityType( ) 

Gets the name of the mapped or federated entity type. 40 
Returns: 

federated entity type 
public abstract void setMappedEntityType(short 
mappedEntityiype) 

Sets the name of the mapped or federated entity type. 45 

Parameters: 

mappedEntityName — federated entity type 
public abstract String getAssocMappedEntityName( ) 

Gets the name of the associated mapped or federated 50 

entity. 
Returns: 

associated federated entity name 
public abstract void setAssocMappedEntityName(String 
assocMappedEntityName) 5 $ 

Sets the name of the associated mapped or federated 
entity. 

Parameters: 

mappedEntityName — associated federated entity name &Q 
public abstract String getAssocEntityName( ) 

Gets the name of the associated native entity. ■ ■ - 
Returns: 

associated native entity name, for example this could be 
the index class name if the server type is DL/VI, or it 65 
could be the application group name if the server type 
if OnDemand. 
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public abstract void setAssocEntityName(String 
assocNativeEntityName) 

Sets the name of the associated native entity. 
Parameters: 

nativeEntityName — name of the associated native entity 
(index class name for example) 
public abstract String getAssocServerName( ) 

Gets the name of the associated server where native 

attributes are defined. 
Returns: 

associated server name 
public abstract void setAssocServerName(String 
assocServerName) 

Sets the name of the associated server where native 

attributes are defined. 
Parameters: 

serverName — back-end associated server name 
public abstract dkAttrMapping getAttrMapping(String 
attrMappingName) throws DKException 

Gets an existring attribute mapping given its name. 
Parameters: 

attrMappingName — federated entity mapping name to be 
retrieved 

Throws: DKException 

an error occurs in the Datastore 
public abstract dkCollection listAttrMappings( ) throws 
DKException 

Lists all existing attribute mapping defined in this schema 

mapping. 
Returns: 

a collection of dkAttrMapping objects defining the map- 
ping. 

Throws: DKException 

an error occurs in the Datastore 
public abstract String[ ] listAttrMappingNames( ) throws 
DKException 

Lists all existring attribute mapping names defined in this 

schema mapping. 
Returns: 

an array of attribute mapping names. 

Throws: DKException 

an error occurs in the Datastore 
public abstract void retrieve( ) throws DKException 

Retrieves this mapping from federated database 

Throws: DKException 

an error occurs in the Datastore 
public abstract dkAttrMapping 

getAttrMappingByMappedName(String mappedAttrName) 
throws DKException 

Gets attribute mapping object by the given the mapped 

attribute name 
Returns: 

attribute mapping object 
public abstract dkAttrMapping 

getAttrMappingByMapToName(String mapToAttrName) 
throws DKException 

Gets attribute mapping object by the given the map-to 
attribute name. 
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Returns: Sets the name of the mapped or federated entity type, 

attribute mapping object Parameters: 

DKSchemaMappingFed is used for mapping in a feder- mappedEntityName— federated entity type 
ated composition. An example class definition for 

DKSchemaMappingFed is set forth below. publicString getAssocMappedEntityName( ) 



DKSchemaMappingFed 

package com. ibm.mm.sdk. common. DKSchemaMappingFed 
public class DKSchemaMappingFed 
extends Object 

implements dkSchemaMapping, DKConstantFed, DKMessageldFed, Serializable 

{ 

public DKSchemaMappingFedQ 

public DKSchemaMappingFed(String name) 

public DKSchemaMappingFed (dkDatas tore ds) 

public String getName() 

public void setName(String name) 

public String getServerNameQ 

public void setServeiName(Stiing serverName) 

public String getServerType() 

public void setServeiType (String serverType) 

public String getEntityNameO 

public void setEntityName(Slring nativeEntityName) 

public String getMappedEntityNameQ 

public void setMappedEntityName(String mappedEntityName) 
public short getMappedEntityTypeQ 
public void setMappedEntityType(short mappedEntityType) 
public String getAssocMappedEntityNameO 

public void setAssocMappedEntityName(String assocMappedEntityName) 
public String getAssocEntityNameO 

public void setAssocEntityName(String assocNativeEntityName) 

public String getAssocServerName() 

public void setAssocServerName(String assocServeiName) 

public void addAttrMapping(dkAttrMapping attrMapping) throws DKException 

public void removeAttrMapping(String attrMappingName) throws DKException 

public dkAttrMapping getAttrMapping(String attrMappingName) throws DKException 

public dkCollection UstAttrMappingsO throws DKException 

public String[] listAttrMappingNamesO throws DKException 

public void ietrieveQ throws DKException 

public void add() throws DKException 

public void updateO throws DKException 

public void del() throws DKException 

public dkAttrMapping getAttrMappingByMappcdName(String mapped AttrName) throws 
DKException 

public dkAttrMapping getAttrMappingByMapToName(String mapTbAttrName) throws 

DKException 
public void setDatastorefdiDatastore ds) 
} 



45 



The following methods are part of the DKSchemaMap- 
pingFed class: 
public DKSchemaMappingFed( ) 
public DKSchemaMappingFed(String name) 
public DKSchemaMappingFed(dkDatastore ds) 
public String getName( ) 
public void setName(String name) 
public String getServerName( ) 
public void setServerName(String serverName) 
public String getServerType( ) 
public void setServeriype(String serverType) 
public String getEntityName( ) 
public void setEntityName(String nativeEntityName) 
public String getMappedEntityName( ) 
public void setMappe dEntity Nane(String 
mappedEntityName) 
public short getMappedEntityType( ) 

Gets the name of the mapped or federated entity type. 

Returns: 

federated entity type 
public void setMappedEntityType(short mappedEntityType) 



Gets the name of the associated mapped or federated 

entity. 
Returns: 

associated federated entity name 
public void setAssocMappedEntityName(String 
assocMappedEntityName) 

Sets the name of the associated mapped or federated 
entity. 

Parameters: 

mappedEntityName — associated federated entity name 
public String getAssocEntityName( ) 

Gets the name of the associated native entity. 
Returns: 

associated native entity name, for example this could be 
the index class name if the server type is DL/VI, or it 
could be the application group name if the server type 
if OnDemand. 

public void setAssocEntityName(String 
assocNativeEntityName) 

Sets the name of the associated native entity. 
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Parameters: 

nativeEntityName — name of the associated Dative entity 

(index class name for example^ 
public String getAssocServerName( ) 

Gets the name of the associated server where native 

attributes are defined. 
Returns: 

associated server name 
public void setAssocServerName(String assocServerName) 
Sets the name of the associated server where native 

attributes are defined. 
Parameters: 

serverName — back-end associated server name, 
public void addAttrMapping(dkAttrMapping attrMapping) 
throws DKException 

public void removeAttrMapping(String attrMappingName) 
throws DKException 

public dkAttrMapping getAttrMapping(String 
attrMappingName) throws DKException 
public dkCollection listAttrMappings( ) throws DKExcep- 
tion 

public String[ ]listAttrMappingNames( ) throws DKExcep- 
tion 

public void retrieve( ) throws DKException 

public void add( ) throws DKException 

public void update( ) throws DKException 

public void del( ) throws DKException 

public dkAttrMapping getAttrMappingByMappedName 

(String mappedAttrName) throws DKException 

Gets attribute mapping object by the given the mapped 
attribute name. 

Returns: 

attribute mapping object, 
public dkAttrMapping getAttrMappingByMapToName 
(String mapToAttrName) throws DKException 

Gets attribute mapping object by the given the map-to 
attribute name. 

Returns: 

attribute mapping object, 
public void setDatastore(dkDatastore ds) 

CONCLUSION 

This concludes the description of the preferred embodi- 
ment of the invention. The following describes some alter- 
native embodiments for accomplishing the present inven- 
tion. For example, any type of computer, such as a 
mainfame, minicomputer, personal computer, mobile 
device, or embedded system, or computer configuration, 
such as a timesharing mainframe, local area network, or 
standalone personal computer, could be used with the tech- 
niques of the present invention. 

The foregoing description of the preferred embodiment of 
the invention has been presented for the purposes of illus- 
tration and description. It is not intended to be exhaustive or 
to limit the invention to the precise form disclosed. Many 
modifications and variations are possible in light of the 
above teaching. It is intended that the scope of the invention 
be limited not by this detailed description, but rather by the 
claims appended hereto. 

What is claimed is: 

1. A method of manipulating data in one or more hetero- 
geneous datastores at a computer, the method comprising the 
steps of: 

providing an object-oriented model for integrating one or 
more heterogeneous datastores with a federated datas- 
tore; 



generating objects representing the one or more hetero- 
geneous datastores and the federated datastore based on 
the object-oriented model; and 
organizing the generated datastores into a federated com- 
5 position. 

2. The method of claim 1, wherein each datastore is a 
datastore object whose class is based on a base datastore 
class. 

3. The method of claim 1, further comprising storing data 
10 within the datastores in the form of objects. 

4. The method of claim 3, wherein the objects are 
dynamic data objects. 

5. The method of claim 3, wherein objects are extended 
data objects. 

!5 6. The method of claim 5, wherein the extended data 

objects comprise binary large objects. 
7. The method of claim 1, further comprising retrieving 

data from one or more of the heterogeneous datastores in 

response to a query to the federated datastore. 
20 8. The method of claim 7, further comprising retrieving 

data using one or more search engines. 

9. The method of claim 7, further comprising retrieving 

data by mapping between the federated datastore and one or 

more heterogeneous datastores. 
25 10. The method of claim 1, further comprising returning 

a group of objects in response to a query for data. 

11. The method of claim 10, further comprising iterating 
through the group of objects. 

12. The method of claim 1, further comprising enabling 
30 querying of a combination of data. 

13. The method of claim 1, farther comprising dynami- 
cally modifying the federated composition. 

14. An apparatus for manipulating data in one or more 
heterogeneous datastores, comprising: 

35 a computer having one or more heterogeneous datastores; 
and 

one or more computer programs, performed by the 
computer, for providing an object-oriented model for 
integrating one or more heterogeneous datastores with 
40 a federated datastore, generating objects representing 
the one or more heterogeneous datastores and the 
federated datastore based on the object-oriented model, 
and organizing the generated datastores into a federated 
composition. 

45 15. The apparatus of claim 14, wherein each datastore is 
a datastore object whose class is based on a base datastore 
class. 

16. The apparatus of claim 14, further comprising storing 
data within the datastores in the form of objects. 
50 17. The apparatus of claim 16, wherein the objects are 
dynamic data objects. 

18. The apparatus of claim 16, wherein objects are 
extended data objects. 

19. The apparatus of claim 18, wherein the extended data 
55 objects comprise binary large objects. 

20. The apparatus of claim 14, further comprising retriev- 
ing data from one or more of the heterogeneous datastores 
in response to a query to the federated datastore. 

21. The apparatus of claim 20, further comprising retriev- 
60 ing data using one or more search engines. 

22. The apparatus of claim 20, further comprising retriev- 
ing data by mapping between the federated datastore and 
one or more heterogeneous datastores. 

23. The apparatus of claim 14, further comprising return - 
65 ing a group of objects in response to a query for data. 

24. The apparatus of claim 23, further comprising iterat- 
ing through the group of objects. 
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25. The apparatus of claim 14, further comprising 31. The article of manufacture of claim 29, wherein 
enabling querying of a combination of data. objects are extended data objects. 

26. The apparatus of claim 14, further comprising 32. The article of manufacture of claim 31, wherein the 
dynamically modifying the federated composition. extended data objects comprise binary large objects. 

27. An article of manufacture comprising a program 5 ^™ . - - A e i 

j- 1 1 * 1 , , , • 33. The article of manufacture or claim 27, further corn- 
storage medium readable by a computer and embodying one . . . . ' 

or more instructions executable by the computer to perform P nsm g retrieving data from one or more of the heteroge- 

method steps for manipulating data in one or more hetero- Deous ^stores m response to a query to the federated 

geneous datastores at a computer, the method comprising the datastore. 

steps of: 10 34. The article of manufacture of claim 33, further corn- 
providing an object-oriented model for integrating one or prising retrieving data using one or more search engines, 
more heterogeneous datastores with a federated datas- 35. The article of manufacture of claim 33, further com- 
tore; prising retrieving data by mapping between the federated 
generating objects representing the one or more hetero- datastore and one or more heterogeneous datastores, 
geneous datastores and the federated datastore based on 15 36. The article of manufacture of claim 27, further com- 
the object-oriented model; and prising returning a group of objects in response to a query 
organizing the generated datastores into a federated com- f or data, 
position. 3 7 jjjg artic]e of manu f actur e of claim 36, further com- 

28. The article of manufacture of claim 27, wherein each „ • • „ :^ raf - „ ^ n „ n n e ■ • . 

j . , , A t . A , , . , ' , , 20 prising iterating through the group or objects, 

datastore is a datastore object whose class is based on a base „ n V™ . , - „ , . ~_ , . 

datastore class e artic ^ e °* manufacture of claim 27, further com- 

29. The article of manufacture of claim 27, further com- P risin S querying of a combination of data, 
prising storing data within the datastores in the form of The article of manufacture of claim 27, further corn- 
objects, prising dynamically modifying the federated composition. 

30. The article of manufacture of claim 29, wherein the 

objects are dynamic data objects. ***** 
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